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HOW THIS MANUAL IS ORGANIZED 


About This Manual 


This JBM AS/400 Languages: PL/I User’s Guide and Reference manual provides 
you with the information you need to write, compile, run, test, and maintain PL/I 
programs on the AS/400! System. 


Note: This manual describes PL/I as it is used on the AS/400 System. In certain 
cases, however, it may be useful to also know the System/38 method. These 
methods are summarized or otherwise described in Appendix F, “Converting from 
System/38 to the AS/400 System.” To find out how to use PL/I in the System/38 
Environment, you should refer to IBM System/38 PL/I Reference Manual and Pro- 
grammer’s Guide, SC09-1051/. 


Cc Who Should Use This Manual 


This manual is meant for programmers who have some knowledge of and experi- 
ence in programming with PL/I. 


How This Manual is Organized 


This manual is divided into two parts. Part | is the user’s guide to PL/I and Part 2 
{ contains reference information. 


¢ Part 1 is intended to give you the basic information you need to write PL/I pro- 
grams. Here you will find an introduction to the language and a description of 
how to actually create, compile, run, test, and debug your PL/I program. 


e Part 2 is a catalogue of reference information that you can refer to while using 
PL/I. Part 2 contains material on program elements, organization and use of 
data types, data management, and AS/400 files. You will also find material on 


* compiler directives, PL/I statements, references, expressions, and a detailed 
C description of PL/I procedures, subroutines, functions, and pseudovariables. 
Following Part 2 is a series of appendixes containing information that might be 
‘ useful to PL/I users. These include: 
e Appendix A, “Compiler Service Information” 
¢ Appendix B, “The AS/400 PL/I Language Summary and Character Set” 
e Appendix C, “Valid Combinations of Options for Input/Output Statements” 
« Appendix D, “Conditions and Condition Codes” 
¢ Appendix E, “EBCDIC CODES” 
e Appendix F, “Converting from System/38 to the AS/400 System” 


Appendix G, “Glossary of Acronyms.” 


1 AS/400 is a trademark of International Business Machines Corporation 
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What You Should Know 


This manual also contains a glossary of the AS/400 System and PL/I terms used in 
this manual that might not be familiar to you, and an alphabetically organized index 
at the back. 


What You Should Know 


Before you use this manual, you should be familiar with the information contained 
in the following IBM AS/400 publications: 


¢« CL Programmer's Guide, which contains the basic concepts of the control 
program functions. 


« You should be familiar with your display station (also known as a work 
station), and its controls. There are also some elements of its display and 
certain keys on the keyboard that are standard regardless of which software 
system is currently running at the display station, or which hardware system the 
display station is hooked up to. Some of these keys are: 


— Cursor movement keys 
— Command keys 

— Field exit keys 

— Insert and delete keys 
— The Error Reset key. 


This information is contained in Systern Operations: Display Station User's 
Guide, SC21-9744. 


¢ You should know how to operate your display station when it is hooked up to 
the IBM AS/400 System and running the AS/400 System software. This means 
knowing about the IBM Operating System/400 (OS/400) and the Control Lan- 
guage (CL) to do such things as: 


— Sign on and sign off the display station 

— Interact with displays 

— Use Help 

— Enter control commands and procedure commands 
— Call utilities 

— Respond to messages. 


To find out more about this operating system and its control language, refer to: 


— Programming: Control Language Reference, SBOF-0481 

— Programming: Control Language Programmer's Guide, SC21-8077 
— Programming: Command Reference Summary, SC21-8076 

— Programming: System Reference Summary, SC21-8104 

— Programming: Data Management Guide, SC21-9658 


¢ You should know how to call and use certain utilities available on the AS/400 
System: 


— The Screen Design Aid (SDA) utility used to design and code displays. This 
information is contained in Application Development Tools: Screen Design 
Aid User's Guide and Reference, SC09-1171. 

— The Source Entry Utility (SEU), which is a full-screen editor you can use to 
enter and update your source and procedure members. This information is 
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If You Need More Information 


contained in Application Development Tools: Source Entry Utility User's 
Guide and Reference, SCO9-/172. 


You should know how to interpret displayed and printed messages. This infor- 
mation is contained in Chapter 3, “Testing and Debugging PL/I Programs” on 
page 3-1 


You should be familiar with the PL/I program cycle, how indicators affect the 
program cycle, and how to code entries on the PL/I specification sheets. 


If You Need More Information 


You might need to refer to other AS/400 System manuals for specific information 
about a particular topic. They are listed below: 


Information Directory, GC21-9678, which contains a brief description of each 
manual in the AS/400 library and information on how to order additional publi- 
cations. 


Licensed Programs Installation Guide, SC21-9765, which describes how to 
install PL/I on your system. 


System Operations: Operator's Guide, SC21-8082, which describes how to 
operate the AS/400 System. 


Programming: Data Description Specifications Reference, SC21-9620, which 
describes data description specifications that are used for describing files. 


Communications: Distributed Data Management User's Guide, SC2/-9600, 
which contains information about remote communication for the PL/I pro- 
grammer. 


Programming: Data Base Guide, SC2/-9659, which contains a detailed dis- 
cussion of the AS/400 data base structure. This manual also describes how to 
use Data Description Specifications (DDS) keywords. 


Communications: Programmer's Guide, SC2/-9590, which provides information 
an application programmer needs to write applications that use the AS/400 
System communications and the Intersystem Communications Function file. 


Programming: Graphical Data Display Manager Programming Reference, 
S'C33-0537, and Programming: Graphical Data Display Manager Programming 
Guide, SC33-0536, which provide guidance on the Graphical Data Display 
Manager (GDDM) for programmers who need to write graphics applications. 


System/38 Environment Programmer's Guide and Reference, SC2/1-9755, which 
describes migrating from System/38 and converting to the AS/400 System. 


Programming: Structured Query Language/400 Reference, SC2/-9608, which 
provides detailed information on using Structured Query Language (SQL) state- 
ments. 


For limitations that may apply to your program but which do not come from 
PL/I, see the Programming: Control Language Programmer's Guide, SC2/-8077. 
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How to Read the Syntax Diagrams 
Throughout this manual, syntax is described using the structure outlined below. 


¢ Read the syntax diagrams from left to night, top to bottom, following the path 
of the line. 


The »»—— symbol indicates the beginning of a statement. 


The ——> symbol indicates that the statement syntax is continued on the next 
line. 


The »—— symbol indicates that a statement is continued from the previous line. 
The ——>~< symbol indicates the end of a statement. 


Diagrams of syntactical units, other than complete statements, start with the 
>—— symbol and end with the —~~ symbol. 


¢ Required items appear on the main path. 


>>——statement required item—————_————->~ 


¢ Optional items appear below the main path. Items will appear in a vertical 
stack if more than one option is available. 


>>——statement 
[opt iona choice1— 
optional choice2 


One item of a vertical stack appearing on the main line indicates that at least 
one option is mandatory. 


pie Sra enent rapped e se nial 
required choice2 


¢ An arrow returning to the left above the main line indicates a single item that 
can be repeated, or an additional option selected from a vertical stack. 


The repeat arrow will also indicate any punctuation, such as a comma, that is 
required between selections. 


bd 


>>——statement repeatable ite 
optional choicel 


optional choice2 


¢ Enter words in UPPERCASE characters as shown, unless an abbreviation 1s 
indicated. Words in lowercase characters represent variable values, and are 
described following the syntax diagram. 


e All round brackets, arithmetic and logical operators, and punctuation must be 
entered where shown. 
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« The underscore on any item denotes a default attribute. 


Note: For ease of readability, syntax in some areas of the manual will deviate from 
the above description, as follows: 


« Square brackets indicate optional items. 
¢ Vertical bars indicate a choice of items. 


e Braces indicate mandatory syntactic expressions. 


The following example shows the syntax for the OPEN statement. 


>>—(0PEN——FILE(file constant) 


8 


i I 5 NS he 
ere ia 


The following is the interpretation for the above sample syntax: 


The start of the syntax diagram. 

The keyword OPEN must be entered. 

The keyword FILE(file_constant) must be entered. 
EJ] Brackets indicate mandatory part of syntax. 

The syntax is continued at JJ. 

[4 Various options available with the OPEN statement. 
The syntax is continued from fj. 

EE] The end of the syntax diagram. 
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Language Extensions 


Language extensions are indicated by enclosing the descriptions of the extension in 
special frames: 


| Full Language Extension i aa 


These brackets indicate language extensions that are part of the complete PL/I 
(ANSI PL/I X3.53-1976). 


fe eee es End of Full Language Extension nner: 
| IBM Extension | 


These brackets indicate language extensions that occur in more than one PL/I com- J 
piler, and that are not part of either the complete PL/I (ANSI PL/I X3.53-1976) or 
the general-purpose subset (ANSI PL/I X3.74-1981). 


bee End of IBM Extension en 


Industry Standards 


The AS/400 PL/I Licensed Program is designed according to the specifications of the Jd 
following industry standards as understood and interpreted by 1BM as of January 

1981: American National Standards (ANS) PL/I, X3.53-1976, which is technically 

identical to International Organization for Standardization (ISO) 6160-1979, and 

European Computer Manufacturers Association (ECMA) (1976) 


The AS/400 PL/I, which is described in this publication, is based on the American 
National Standards Programming Language PL/I General-Purpose Subset, 
X3.74-1981, with the following differences: 


e Restrictions and omissions from the above subset. } 


¢ Extensions based on features of the American National Standard Programming 
Language PL/I, X3.53-1976. 


¢ Extensions based on common features added by IBM. 


e Extensions based on PL/I features added by IBM. 


For a complete description of the source of each feature of the language, refer to 
Appendix B, “The AS/400 PL/I Language Summary and Character Set.” 


The AS/400 PL/I Licensed Program 
The AS/400 PL/I consists of the following: 


e A PL/I compiler ) 
« An interface to Source Entry Utility (seU) for checking PL/I syntax. 
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C What Your AS/400 System Needs to Run PL/I 


The AS/400 PL/I Licensed Program (5728-PL1) is run by the IBM Operating 
System/400 (OS/400) Licensed Program (5728-SS1) on any size AS/400 System that 
has at least one 1920-character 5250 (or functionally compatible) work station. 


The AS/400 PL/I is installed in a separate user library, called QPLI. See the 
Licensed Programs Installation Guide, SC2/-9765 for information on installing PL/I. 
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Part 1. User’s Guide 


Part | is a user’s guide. It contains the basic information you need to program in 
AS/400 PL/I. This information is organized sequentially to allow you to read 
through it and develop an understanding of PL/I programming: how to create, 
compile, run, test, and debug your program. 
The user’s guide is organized into: 

e Chapter 1, “An Introduction to PL/I and the AS/400 System” 

e Chapter 2, “Creating, Compiling, and Running Your PL/I Program” 


e Chapter 3, “Testing and Debugging PL/I Programs.” 
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ACCESSING PL/I on the AS/400 System 


Chapter 1. An Introduction to PL/I and the AS/400 System 


This chapter is a brief introduction to using AS/400 PL/I. The topics include: 


The AS/400 Operating System and Control Language 
Accessing PL/I from 0s/400 


The AS/400 Operating System and Control Language 
The AS/400 Operating System 


The operating system that controls all your interactions with the AS/400 System is 


called Operating System/400 (OS/400). From your display work station, OS/400 
allows you to: 


Sign on and sign off the AS/400 System 
Interact with the displays 

Use Help 

Enter control commands and procedures 
Respond to messages 

Manage files 

Call up other utilities and run other programs. 


The AS/400 Control Language 


You interact with the AS/400 System by entering or selecting Control Language 
(CL) commands. 


The AS/400 CL commands you will be using most often with PL/I are: 


c | 


STRSEU to call up the Source Entry Utility (SEU), a full-screen editor that can be 
used to enter PL/I program code 

CRTPLIPGM to compile PL/I source programs 

CALL program-name to run a PL/I program 

CALL QCL to access the System/38 Environment 

RETURN to exit from System/38 Environment. 


The Control Language and all its commands are described in detail in the Program- 
ming: Control Language Reference. 


Accessing PL/I on the AS/400 System 


When you start working on the AS/400 System, you will see the following screen. 
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System . . e+ eo 3 
Subsystem 
Display... 


Password 

Program/procedure ..... 
Menu. ew ew ew wwe 

Current library 


error message line © COPYRIGHT IBM CORP. 1988 


Figure 1-1. The AS/400 System Sign-on Screen 


The following screen appears, when you enter your ID and password, and you can 
begin working on the AS/400 System. 


MAIN AS/400 Main Menu 
System: XXXXXXXX 
Select one of the following: 


. User tasks 

. Office tasks 

. General system tasks 

. Files, libraries, and folders 
Programming 

Communications 

Define or change the system 

- Problem handling 

. Display a menu 


oan um & WYP 


oO 
[<>] 


. Sign off 


Selection or command 


===> 


FI=Exit F4=Prompt F9=Retrieve F12=Previous Fl3=User Support 
F23=Set initial menu 


© COPYRIGHT IBM CORP. 1988 


Figure 1-2. AS/400 Main Menu Screen 


To begin working in PL/I, enter or select the appropriate CL command. 
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CREATING AND EDITING PROGRAMS 


Chapter 2. Creating, Compiling, and Running Your PL/I 
Program 


To run a progtam, you must enter and store it on the AS/400 System as a source 
file, and then compile it. You can connect programs written in different languages, 
including PL/I, and run the PL/I program as part of a system of programs. The 
chapter describes: 


¢ Creating and editing the source program 

¢ Compiling your source program using the CRTPLIPGM command 
¢ Using compiler directives 

¢« Running the program 

¢ Compiler output 

¢ Interlanguage calls. 


Creating and Editing the Source Program 


You can enter your source program onto the system interactively, by using the 
Source Entry Utility (szU). Enter the CL command STRSEU (Start SEU) to call SEU. 


For a description of how to use the STRSEU command, refer to the SEU User's 
Guide and Reference. 


You can enter your source program onto the system in batch mode (for example, 
from diskettes) by using the OS/400 copy or spooling functions. For more informa- 
tion on how to use the copy and spooling functions for batch entry, refer to the 
Programming: Data Management Guide. 


The first procedure in creating your program is to name the file that will store the 
source program. The AS/400 file naming convention that you use to do this is 
library-name/file-name. 


Note: A PL/I program that is entered in the System/38 Environment should also be 
compiled and run in the System/38 Environment. The program can access 
any file unless the file name contains characters other than A-Z, 0-9, #, @, 
and _. Because this restriction does not apply to AS/400 file names, you 
may not be able to use a AS/400 file from the System/38 Environment. 


On the AS/400 System, you can use upper or lowercase characters in a file 
name or a member name. However, all lowercase characters are converted to 
uppercase in the System/38 Environment. 
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Using SEU to Create and Edit a Source Program 
SEU provides you with a screen that you can use to enter your source program, and 
a PL/I syntax checker that checks each line for errors as you enter it. There are also 
three screens that you can use for various functions on a file you are editing. The 
screens are: 


¢ The Edit Services Screen shown in Figure 2-1 on page 2-3 
e The Find/Change Services Screen shown in Figure 2-2 on page 2-3 
¢ The Browse/Copy Services Screen shown in Figure 2-3 on page 2-4. 


The PL/I Syntax Checker 


The following commands allow you to use the PL/I syntax checker. 


¢ The CL command STRSEU TYPE(PLI) accesses SEU with the PL/I syntax checker 
in effect. You can also select the TYPE(PLI) parameter from the SEU edit ser- 
vices screen (see Figure 2-1 on page 2-3). 


¢ The CL command STRSEU TYPE(TEXT) accesses SEU as an editor only; no syntax 
checker is in effect. 


e The CL command STRSEU TYPE(PLI38) calls up the System/38 PL/I syntax 
checker. The syntax rules for System/38 PL/I apply. 


If you use the PL/I syntax checker while entering your source program, pressing 
Enter at any time automatically processes the syntax checker on any line that has 
been changed and on any new lines that have been added to the screen. Any state- 
ment that contains a syntax error is then shown in reverse image, and an error 
message appears on the screen telling you what is wrong with the statement. When 
you correct the error and press Enter, the error message 1s taken off the screen and 
the normal image of the statement is restored. 


The syntax checker only checks individual statements, independently of preceding 
statements. Therefore no errors based on relationships with other statements are 
detected. For instance, if you declare WAGETOT at the beginning of your 
program and misspell the variable name in a later statement 


WAGETOTAL = CURMONTHTOTAL + YTDTOTAL; 


no error is detected. Similarly, if you make an error in nesting loops and code too 
many END statements, the syntax checker cannot detect the error. This type of 
error is found when you compile the source program. 
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Type choices, press Enter. 
Amount to roll ...... 


Uppercase input only.... 
Tabs on 

Increment of insert record 
Source type 
Syntax checking: 


When added/modified 
From sequence number 
To sequence number . 
Left margin 
Right margin... . 
Set records to date . 
Screen size 


FS=Exit 
F14=Find/Change Services 


F5=Refresh 
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Edit Services 


l=Half page 
2=Full page 
Y=Yes, N=No 
Y=Yes, N=No 
0.01 to 999.99 


Y=Yes, N=No 
9000.00 to 9999,99 
0000.00 to 9999.99 
1 to 80 

1 to 80 

YY/MM/DD or YYMMDD 
1=27x132, 2=24x80 


F12=Previous 
F15=Browse/Copy Services 


Figure 2-1. SEU Edit Services Screen 


Find/Change Services 


Type choices, press Enter. 
FInd: eel oe ee aren ee 
Change ... 
From column number .. 
To column number ... 
Allow data shift 
Occurrences to process 


Records to search.... 
Kind of match. .... 


Search for date.... 
Compare... ...- 


F3=*Exit F5=Refresh 
F15=Browse/Copy Services 


F12=Previous 
F16=Find 


88/11/19 


Figure 2-2. SEU Find/Change Services Screen 


1 to 80 

1 to 80 

Y=Yes, N=No 
l=Next, 2=Al] 
3=Previous 

1l=All, 2=Excluded 
3=Non-exc]uded 
l=Same case 


2=Ignore case 
YY/MM/DD or YYMMDD 
l=Less than 
2=Equal to 
3=Greater than 


Fl3=Edit Services 
F17=Change 
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Browse/Copy Services 
Type choices, press Enter. 
Selection 1=Member 
2=Spool file 
3=Output queue 
Copy all records Y*Yes, N=No 
Browse/copy member Name, F4 for list 
Library Name, *CURLIB, *LIBL 
File Name 
Name 
Name 
BRODEUR Name 


Job number *LAST Number, *LAST 
Spool number *LAST Number, *LAST, *ONLY 
Display output queue QPRINT Name, *ALL 
Library *LIBL Name, *CURLIB, *LIBL 


F3=Exit F5=Refresh F12=Previous 
F13=Edit Services F14=Find/Change Services 


Figure 2-3. SEU Browse/Copy Services Screen 


The PL/I syntax checker sets the margins for your source entry to column 2 and 
column 72. You can see the margin settings by looking at the lower right-hand 
corner of your file’s services screen. For normal PL/I programming this is the 
standard and desirable setting, but at times you may need to change the setting. For 
instance, the % PROCESS directive must begin in column 1. % PROCESS is not 
valid if it begins in any other column. In this case, you should alter the left margin 
to column | so that you can enter the %PROCESS directive correctly. You use 
the Edit Services screen and change the column number for the left margin from 002 
to 001. If you change the margin to 001, you must make sure that the standard PL/I 
statements in your program do not begin in the first column of the screen. 


SEU automatically runs the PL/I syntax checker whenever there are lines that are 
changed or added on the screen. The new source program is then passed to the 
syntax checker one statement at a time. Because PL/I source data can be entered in 
free format and its statements can span more than one line, SEU uses the semicolon 
to determine the statement boundaries. 


Note: The scanning of the semicolon in the backward direction to find the start of a 
statement may occasionally produce unwanted results when the semicolon is 
imbedded inside a comment or a string literal, or when the % INCLUDE directive is 
used in the middle of a statement. 


Using SEU to Browse a Compiler Listing 
You may use the SEU split-edit display to browse through a compiler listing that is 


on an output queue. For more information on browsing through a compiler listing, 
see the SEU User’s Guide and Reference. 
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Entering SQL Statements into a PL/I Program 


The Structured Query Language (SQL) is a high level data base storage and retrieval 
language that uses structured techniques. You can place SQL statements into a PL/I 
program at any point using the SEU to enter the statements. 


To enter SQL statement(s) into a PL/I program, you would enter: 
EXEC SQL sql-statement; 


Each sQL statement should end with a semicolon and must be on a separate line. 
The Programming: Structured Query Language/400 Reference describes SQL in 
detail. 


Note: SQL statements are recognized and syntax checked by the editor only; not the 
compiler. They are not processed. 


If your program contains SQL statements, you must call the sQL preprocessor before 
using CRTPLIPGM to compile the source program. Refer to Programming: 
Structured Query Language/400 Reference for a description of how this is done. 
This is not necessary if the source program has no SQL statements. 


Compiling Your Source Program Using the CRTPLIPGM Command 


To compile a PL/I source program use the CL command CRTPLIPGM (Create PL/I 
Program). The compiler checks the syntax of each line of the PL/I source program, 
and checks relationships among the lines. By selecting options with the 
CRTPLIPGM command, you can request a program object, a compiler listing, or 
any of the other options provided. You may use the command directly from 
OS/400, in a CL program, or in interactive or batch mode. 


You can use compiler directives in your PL/I source program to direct some of the 
operations of the PL/I compiler. Compiler directives allow you to: 
¢ Copy external text into the program 


¢ Copy data description specifications for externally described files into the 
program 
¢ Control batch compilation 


e Control the format of the program listing. 
For more information, see “Using Compiler Directives” on page 2-16. 


When compiling takes place, an attribute character string is produced that specifies 
the environment that the program was compiled in. The character string is PLI for 
the AS/400 System and PL138 for the System/38 Environment. Other differences in 
compiling in the System/38 Environment are described in “Compiling in the 
System/38 Environment” on page F-1. 


If the compilation is successful, a message identified by code PLC000S is sent and 


the return code is set to zero. If the compilation is not successful, a message identi- 
fied by code PLC9001 is sent and the return code is set to 2. The CL command 
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MONMSG (Monitor Message) can be used in a CL program to monitor for these J 
messages. 


All object names specified on the CRTPLIPGM command must be composed of 
alphanumeric characters, the first of which must be alphabetic. The length of the 
names cannot exceed ten characters. See Programming: Control Language Refer- 
ence for a detailed description of OS/400 object naming rules and for a complete 
description of CL command syntax. 


Completing the First CRTPLIPGM Screen 


CRTPLIPGM Create PL/I Program 
Type choices, press Enter. 
*PROC Name, *PROC 


*CURLIB Name, *CURLIB 
Source file QPLISRC Name ‘ 


Library *LIBL Name, *LIBL, *CURLIB 
Source member *PGM Name, *PGM 
Generation severity level ... 15 0-29 
Text ‘description’ *SRCMBRIXT 


F3=Exit F4=List F5=Refresh F10=Additional parameters F11l=Keywords 
Fl2=Previous F13=Prompter help 


Figure 2-4. The First CRTPLIPGM Screen 


Each parameter on the screen displays a default value. Move the cursor past items J 
where you want the default value to apply. Type over any items where you want to 

set a different value or option. If you are not sure about the setting of a particular 

parameter, type a question mark (?) as the first character in that field and press 

Enter to receive more detailed information. The ? must be followed by a blank. 


You must enter values for the library and program name by which the compiled 
program is known, and the name of the source file that contains the program 


source. ) 


All other parameters have default values, which you can change if necessary. Press 
F10 to display additional parameters (see Figure 2-5 on page 2-9). Press F3 to exit 
without processing the command. 


The descriptions of the parameters and options follows (the defaults are underlined 
and are explained first). 


PGM 
Specifies the library and program name by which the compiled PL/I program 
is known. If no library is specified, the created program is stored in the 
current library. The program must not already exist in the library. 


*PROC 
The program name is the name of the first external procedure in the 
compilation. If there is more than one program in the compilation, each 
subsequent program name is the name of the first external procedure fol- 2) 
lowing each %PROCESS directive. 
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program-name 


The name by which the program will be known. This name must 
match the name of the first external procedure in the compilation. 


Note: If the name you enter does not match the name of the first 
external procedure in the compilation, there will be an unrecoverable 
error, and the program will not be compiled. 


If there is more than one program in the compilation, each subsequent 
program name is the name of the first external procedure following each 
“PROCESS directive. 


*CURLIB 
The current library will be used. If you have not specified a current 
library, QGPL will be used. 
library-name 
Enter the name of the library where the compiled program will be 
stored. 
SRCFILE 


Specifies the name of the source file that contains the PL/I source program to 
be compiled. 


QPLISRC 
The default source file, QPLISRC, contains the PL/I source file to be com- 
piled. 

source-file-name 


Enter the name of the source file that contains the PL/I source program 
to be compiled. 


Note: The recommended record length of the PL/I source file is 92. If 
the record length is greater than 92, only the first 92 bytes of each record 
is used. The record length must not be less than the value of the right 
margin plus 12. 


*LIBL 
The system searches the library list to find the library where the source 

file is located. 
*CURLIB 

The current library will be used. If you have not specified a current 

library, QGPL will be used. 
library-name 

Enter the name of the library where the source file is stored. 


SRCMBR 
Specifies the name of the member of the source file that contains the PL/I 
source program to be compiled. This parameter can only be specified if the 
source file in the SRCFILE parameter is a data base file. 
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*PGM 
Use the name specified by the PGM parameter as the source file member 
name. The source program will have the same name as the object 
program. If no program name is specified by the PGM parameter the 
system uses the first member created in or added to the source file as the 
source file member name. 


source-fi]e-member-name 
Enter the name of the member that contains the PL/I source program. 


GENLVL 

Specifies whether an object program is generated depending on the severity of 
the errors encountered. A severity level value corresponding to the severity 
level of the messages produced during compilation can be specified with this 
parameter. If errors occur in a program with a severity equal to or greater 
than the value specified in this parameter, the compilation is ended. For 
example, if you do not want a program generated if you have messages with a 
severity level of 20 or greater, specify 20 in this parameter. 


15 
If a severity level value greater than 15 is specified, the program may 


contain errors that will cause unpredictable results when the compiled 
program is run. 


severity-level 
Enter a two-digit number, 01 through 29. 


Note: The severity level value of PL/I messages does not exceed 29. 


TEXT 
Lets the user enter text that bnefly describes the program and its function. 
The text appears whenever the program runs. 


*SRCMBRTXT 
The text of the source member is used. 


«BLANK 
No text appears. 


'description' 
Enter the text that briefly describes the program and its function. The 
text can be a maximum of 50 characters in length and must be enclosed 
in apostrophes. The apostrophes are not part of the 50-character string. 


If these parameter values are sufficient, press F16 to process the command. Other- 
wise, press F10 to display additional parameters. 
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( —_ Completing the Second CRTPLIPGM Screen 


CRTPLIPGM 


Type choices, press Enter. 


Source file 
Library 
Source member 
Generation severity level 
Text ‘description’ 


Compiler options 
+ for more values 
Generation options 
+ for more values 


Create PL/I Program 


*SRCMBRTXT 
Additional Parameters 


Figure 2-5. The Second CRTPLIPGM Screen 


Name, 
Name, 
Name 
Name, 
Name, 
0-29 


*PROC 
*CURLIB 


*LIBL, *CURLIB 
*PGM 


More... 


F3=Exit F4=List F5=Refresh Fll=Keywords [F12=Previous F13=Prompter help 


The additional parameters and their descriptions are listed below. Default values are 


underlined. 
OPTION 


Specifies the options to use when the PL/I source program is compiled. Any 
or all of the options can be specified in any order. Separate the options with a 


C blank space. 


* SOURCE 


Produce a source listing, consisting of PL/I program input and all 
compile-time errors. 


*NOSOURCE 


A source listing is not produced. If «NOSOURCE is specified the system 
defaults to *NOXREF. 


The acceptable abbreviation for *SOURCE is *SRC, and for *NOSOURCE is 


( *NOSRC. 


*XREF 


Produce a cross-reference listing between the items declared in your 
program and the numbers of the statements in your program that refer 
to these items. If you specify both «ATR and «XREF, the attribute table 
and cross-reference listing are combined. 


x NOXREF 


Do not produce a cross-reference listing. 


*SREF 


Produce a cross-reference listing of only referenced names. Unrefer- 
enced names are omitted. 
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*GEN 
Create a program object that can be run after the program is compiled. 


*NOGEN 
Do not create a program object. 


*NOOPTIONS 
Do not list options in effect for this compilation. 


*OPTIONS 
List options in effect for this compilation. 


The acceptable abbreviations for *NOOPTIONS is *NOOPT, and for *OPTIONS 
is *OPT. 


*NOAGGREGATE 
Do not generate an aggregate table. 


*AGGREGATE 
Generate an aggregate table. The aggregate table gives the lengths of all 
arrays and major structures in the source program. 


The acceptable abbreviations for *NOAGGREGATE is *NOAGR, and for 
*AGGREGATE is *AGR. 


*NOATTRIBUTES 
Do not generate a table of the attributes of the identifiers in the source. 


*xATTRIBUTES 
Generate a table of the attributes. If you specify both «ATTRIBUTES and 
*XREF, the attribute table and cross-reference listing are combined. If 
you specify both «ATTRIBUTES and «SREF, the attribute table and cross- 
reference listing for referenced names are combined. 


The acceptable abbreviations for *ATTRIBUTES is *ATR, and for 
*NOATTRIBUTES is *NOATR. 


*NOSECLVL 
Do not list second-level message text for this compilation. 


*SECLVL 
List second-level message text for this compilation. 


GENOPT 
Specifies the options used to create the program object: the printing of the 
IRP (intermediate representation of a program), a cross-reference listing of 
objects defined in the IRP, and the program template. GENOPT reserves a 
program patch area, and specifies optimization of a program for more efficient 
running. These results may be useful if a problem occurs when trying to run 
the compiled program. Any or all of the options can be specified in any 
order. Separate the values with a delimiter. 
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«NOLIST 
Do not list the intermediate representation of the program (IRP), associ- 
ated hexadecimal code, and error messages. If you specify »XREF, «DUMP, 
or «ATR, a listing will be generated, even if you specify »NOLIST. 


*LIST 
List the intermediate representation of the program. 


*NOXREF 
Do not produce a cross-reference listing of all objects defined in the 
IRP. 


*XREF 
Produce, a cross-reference listing of all objects defined in the IRP. If 
you specify *XREF, a listing will be generated, even if you specify 
*NOLIST. 


*NOPATCH 
Do not reserve space in the compiled program for a program patch 
area. The program patch area can be used for debugging. 


*PATCH 
Reserve space in the compiled program for a program patch area. 


*NODUMP 
Do not list the program template. 


*DUMP 
List the program template. If you specify »DUMP, a listing will be gener- 
ated, even if you specify «NOLIST. 


*NOATTRIBUTES 
Do not list the attributes for the IRP source. 


*ATTRIBUTES 
List the attributes for the IRP source. If you specify *«ATTRIBUTES, a 
listing will be generated, even if you specify «NOLIST. 


The acceptable abbreviations for *NOATTRIBUTES is *NOATR, and for 
*ATTRIBUTES is *ATR. 


+ NODIAGNOSE 
Do not process program-checking functions at run time. For more 
information on the functions provided by the «DIAGNOSE option, see 
“The «DIAGNOSE Option of the GENOPT Parameter” on page 2-16. 
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*DIAGNOSE 3 


Process program-checking functions at run time. 


*#NOOPTIMIZE 
Do not process program optimization. 


*OPTIMIZE 
Process program optimization. With *OPTIMIZE the compiler generates 
a program for more efficient processing and that will possibly require less 
storage. However, specifying *OPTIMIZE can substantially increase the 
time required to create the program. Existing object programs may be 
optimized using the CL command CHGPGM. 


If these parameter values are sufficient, press F16 to process the command. Other- 
wise, roll the screen to display additional parameters. ) 


Completing the Third CRTPLIPGM Screen 


CRTIPLIPGM Create PL/I Program 
Type choices, press Enter. 
Source margins 
*SRCFILE 1-80 
1-80 
Include file *SRCFILE Name 


Library Name, *LIBL, *CURLIB ; 
Print file QSYSPRT Name 


Library *LIBL Name, *LIBL, *CURLIB 
Flagging severity 0 0-49 
Replace existing program.... *YES *VES, *NO 
User profile *USER *USER, *OWNER 
Authority *CHANGE Name, *CHANGE, *ALL, *USE... 
Compiler problem determination *NO *NO, *YES 


Bottom 
F3=Exit F4=List F5=Refresh Fll=Keywords F12=Previous F13=Prompter help 


Figure 2-6. The Third CRTPLIPGM Screen ) 


The additional parameters and their descriptions are listed below. Default values are 
underlined. 


MARGINS 
Specifies the part of the compiler input record that contains source text. 


x ORCFILE 
Use the margin values of the file member you specify in the SRCMBR 
parameter. If the file is of type PLI, the margin values are the values 
specified on the SEU services display. If the file is of a different type, the 
margin values are the default values of 2 and 72. 


left, right 
Enter the values for the left and right margins. The margins must not 
be less than 1 or more than 80, and the left margin must be smaller than 


the right margin. ) 
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Note: MARGINS does not apply to the % PROCESS directive, which 


must have a percent sign (%) in column 1. 


INCFILE 
Specifies the qualified name of the source file that contains member(s) 
included in the program with the “INCLUDE directive(s). 


*SRCFILE 
The qualified source file you specify in the SRCFILE parameter con- 
tains the source file member(s) specified on any % INCLUDE 
directive(s) in the program that either specify SYSLIB or do not specify 
a file name. 


source-file-name 
Enter the name of the source file that contains the source file 
member(s) specified on any % INCLUDE directive(s) in the program 
that either specify SYSLIB or do not specify a file name. The record 
length of the source file you specify here must be no less than the record 
length of the source file you specify for the SRCFILE parameter. 


*LIBL 
The system searches the library list to find the library. 


*CURLIB 
The current library will be used. If you have not specified a current 
library, QGPL will be used. 


library-name 
Enter the name of the library where the source file is located. 


PRTFILE 
Specifies the name of the file where the compiler listing is placed and the 
library where the file is located. If you specify a file whose record length is 
less than 132, information will be lost. 


QSYSPRT 


If a file name is not specified, the compiler listing is placed in the 
IBM-supplied file, QSYSPRT. If the file is spooled, the file goes to the 
QPRINT queue. The file QSYSPRT has a record length of 132. 


print-file-name 
Enter the name of the file where the compiler listing is directed. 


*LIBL 
The system searches the library list to find the library. 


*CURLIB 
The name of the current library. If you have not specified a current 
library, QGPL will be used. 


library-name 
Enter the name of the library where the file 1s located. 
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FLAG 
Specifies the minimum severity level of messages to be listed. 


0 


All messages are listed. 


severity-level 
Enter a number that specifies the minimum severity level of the mes- 
sages that are listed. Messages that have severity levels of the specified 
level or higher are listed. 


REPLACE 
Specifies if a new program object will be created when there is an existing 
program object of the same name in the same library. 


*YES 
A new program object will.be created and any existing program object 
of the same name in the specified library will be moved to library 
QRPLOBJ. 


«NO 
A new program object will not be created if a program object of the 
same name already exists in the specified library. 


USRPRF 
Specifies the user profile the compiled PL/I program runs under. This profile 
controls which objects can be used by the program (including what authority 
the program has for each object). 


*USER 
The program runs under the user profile of the program’s user. 


*OWNER 
The program runs under the user profiles of both the program’s owner 
and user. The collective sets of object authority in both user profiles are 
used to find and access objects while the program is running. Any 
objects that are created while the program is running are owned by the 
program’s user. 


Note: The USRPRF parameter reflects the security requirements of your 
installation. The security facilities available on the AS/400 System are 
described in detail in Programming: Control Language Programmer's 
Guide and the Programming: Control Language Reference. 


AUT 
Specifies what authority for the program and its description is being granted 
to the public. The authority can be altered for all or for specified users after 
program creation with the CL commands GRTOBJAUT (Grant Object Authority) 
and RVKOBJAUT (Revoke Object Authority). For further information on these 
commands and for an expanded description of the AUT parameter, see the Pro- 
gramming: Control Language Reference. 


* CHANGE 
The public has operational rights only for the compiled program. Any 
user can run the program and debug it but cannot change it. 
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*USE 
The public can run the program, but cannot debug or change tt. 


#ALL 
The public has complete authority for the program. 


*EXCLUDE 
The public cannot use the program. 


authori zation-list 
Name of an authorization list to which the program is added. Fora 
description of the authorization list and how to create it see the Pro- 
gramming: Control Language Reference. 


Note: Use the AUT parameter to reflect the security requirements of your 
installation. The security facilities available on the AS/400 System are 
described in detail in Programming: Control Language Programmer's 
Guide and the Programming: Control Language Reference. 


SERVICE 
Specifies the use of the compiler problem determination facilities. For a 
description of how to use these facilities, refer to Appendix A, “Compiler 
Service Information.” 


NO 


Deactivate the compiler problem determination facilities while com- 
piling. 


*YES 
Activate the compiler problem determination facilities while compiling. 


Examples 


The following command compiles a program named PAYROL. 
CRTPLIPGM PAYROL TEXT (‘Payroll Program‘) 


The source program is in the default source file QPLISRC, in a member named 
PAYROL. A compiler listing is generated. The program is run under the *USER 
user profile, and can be run by any system user. 


The following command creates a PL/I program named PARTS. 


CRTPLIPGM PGM(PARTS) + 
SRCFILE (MYLIB/PARTDATA) + 
OPTION (*XREF *OPT) AUT (*EXCLUDE) + 
TEXT ('This program displays all parts data’) 


The program object is stored in the library pointed to by *CURLIB. The source 
program is in the PARTS member of the source file PARTDATA in the library 
MYLIB. A compiler listing, cross-reference listing, and compiler-option list is gen- 
erated. This program, which cannot be used by the public, can be run by the owner 
or another user that the owner has explicitly authorized by name with the CL 
command GRTOBJAUT (Grant Object Authority). 
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The «DIAGNOSE Option of the GENOPT Parameter 


The «DIAGNOSE option provides the following program-checking functions at run 
time: 


¢ Checking of substring range for non-adjustable strings is done automatically. 
Because of the many ways a string can be referenced, not all substring range 
violations will be detected. When a string range exception is raised by the 
machine, PL/I raises the ERROR condition. 


¢ The attributes of EXTERNAL variables are matched to their external 
descriptions. If the attributes do not match, a diagnostic message is issued. 


¢ All PL/I runtime informational messages which normally go to the program log 
are also written to the PL/I fille SYSPRINT. Therefore, both user-written debug 
information and compiler-generated information will be intermixed in the order 
in which they occur. 


¢ If you specify «DIAGNOSE, 0S/400, MCH, and PL/I messages will remain on the 
program message queue. 


¢ The STRINGSIZE condition informational message is sent when the 
STRINGSIZE condition 1s raised. 


Using Compiler Directives 


Compiler directives are statements that direct the operation of the compiler. They 
always begin with the percent symbol (%). They are: 


YoINCLUDE 

% PAGE 

% PROCESS (*PROCESS) 
“SKIP. 


The %PAGE and %SKIP directives are listing control directives. 
The %PROCESS statement is used for multiple compilation. 


The %INCLUDE statement has two different uses: 
¢ Copying external text into the source program. 


¢ Copying Data Description Specifications (DDs) for externally described files into 
the source program. 


Using the “INCLUDE Directive 
The %INCLUDE directive can be used to copy external text into the source 
program and copy DDs for externally described files into the source program. 


Including External Text 


The %INCLUDE directive, when used with the following syntax, includes external 
text into the source program. 
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+] 
>>—% INCLUDE ember_name 
(member_name) 


SYSLIB(member_name) 


file_name(member_name) 


member_name 
An identifier of up to ten characters. The name must be unique within one file. 


¢ The member_name specifies the name of the file member included into the 
source program. 


¢ If the member_name appears in more than one file in your library list, and you 
do not specify the file name or SYSLIB, the member used 1s from the first file 
with a member of that name found on the library list. 


e You can specify up to twenty member_names in any % INCLUDE statement. 


SYSLIB 
This name is included for compatibility. If you enter SYSLIB instead of a 
file name, the name used is the one specified on the INCFILE parameter of the 
Create PL/I Program (CRTPLIPGM) command. Refer to “Compiling Your 
Source Program Using the CRTPLIPGM Command” on page 2-5 fora 
description of the parameters of the CRTPLIPGM command. 


file_name 
An identifier of up to ten characters. The file is located by using the *LIBL 
search list in effect at compile time. The file name can begin with and contain 
numeric characters and periods. The valid characters are: A-Z, 0-9, #, $,@, _. 
You cannot name your file SYSLIB. 


SYSLIB and parentheses on either side of a member name are supported for com- 
patibility with other implementations of PL/I. 


Included text can contain % INCLUDE directives, nested to a maximum depth of 
64 levels. 


The included text can be parts of statements. This provides an efficient way of cre- 
ating identical declarations for different structure variables. For example: 


DECLARE 1 A, 
%INCLUDE X; 
DECLARE 1 Y, 
%INCLUDE X; 


where X contains: 


2 B BINARY, 
2 C FIXED; 


results in: 
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DECLARE 1 A, 
2 B BINARY, 
2 C FIXED; 
DECLARE 1 


Y 
2 
2 


oO w 


You can include text that consists of a constant, an identifier, a delimiter, or one 
external procedure. You cannot include any of the following: 


« Parts of constants 

e Parts of identifiers 

e Parts of delimiters 

¢ More than one external procedure 
¢ The %PROCESS directive. 


| IBM Extension | 


Including DDS 


For a discussion of how to use the %INCLUDE directive to copy DDS, see “Using 
the % INCLUDE Directive for External File Descriptions” on page 8-73. 


Pe End of IBM Extension | 
[OO IBM Extension ee 


Using the %PAGE Directive 


The %PAGE directive controls the source program listing when the program is 
compiled. The text following a %PAGE directive is printed in the source program 
listing starting on the first line of the next page. The %PAGE directive does not 
appear in the source program compile listing. 


p>>—%PAGE; >< 


The %PAGE directive must be the only text on a line. No label prefix or comment 
may be specified on this line. 


PO End of IBM Extension | 


Using the %PROCESS Directive 
The %PROCESS directive supports batched compilation. The syntax 1s: 


Nad kee 
> compiler_options 
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C The % or » must be coded in column 1. PROCESS must be coded in columns 2 
through 8. The text and semicolon must be coded in columns 9 through 72 in the 
first line and, if necessary, in columns | through 72 in subsequent lines. Text 
appearing after the semicolon on the same line is ignored. 


The » is provided for compatibility with other compilers. The text or any options 
specified with this directive are ignored. You cannot copy the %PROCESS direc- 
tive into your program with the %INCLUDE directive. If the %PROCESS direc- 
tive precedes the first program in the source file, it must be the first record in the 
file. 


| IBM Extension | 


C Using the %SKIP Directive 


The %SKIP directive controls the source program listing when the program is com- 
piled. The specified number of lines following a %SKIP directive in the program 
listing are left blank. The %SKIP directive does not appear in the source program 
listing. 


ee Le 
(number_of_lines) 


number_of_lines 
An integer constant in the range 1 through 99. It specifies the number of lines 
left blank. If you omit this, 1 is assumed. 


The %SKIP directive must be the only text on a line. No label prefix or comment 
may be specified on this line. 


( If number_of_lines is greater than the number of lines remaining on the page, the 
) rest of the page is skipped and printing continues at the top of the new page. In 
this case, the YoSKIP directive is equivalent to a % PAGE directive. 


PO End of IBM Extension re ere 


Compiler Output 
In this example, the CRTPLIPGM command was entered as follows: 


CRTPLIPGM QTEMP/LP1413 PLIST/PLISRC + 
OPTION(*XREF «OPT *AGR *ATR) + 
GENOPT(*LIST *XREF «PATCH «DUMP «ATR »DIAGNOSE) 


The program source listing can be seen in Figure 8-3 on page 8-5. 


[ The components of the listing that are produced by the various options of the 
GENOPT parameter document the translation of the program into machine lan- 
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5728PL1 R@1 M@O 888715 


5728PL1 RO1 MO@ 880715 


STMT. SUBS 


4B 
2.18 


3.3 
3.1 
3.2 
3 


Ww WwW 
fF aomn 


Identifiers 


BIT_FLAGS 
IN FILE 


IND_FILE 


INDEX_BAL 
INDEX_KEY 
INDEX_ NAME 
INDEX_RECORD 


INPUT_BAL 
INPUT_KEY 
INPUT_NAME 
INPUT_RECORD 
LP1413 
MORE_RECORDS 
NO 


YES 


\ 
guage. They are discussed at “Examples of Using Compiler Debugging Options” on J 
page A-10. 


PL/I 


PL/I 


PL/I Compilation Options PLITST/LP1413 11/30/88 15:51:24 Page 2 
Compiler Options in Effect 
AGGREGATE 
NOATTRIBUTES 
NOSECLVL 
FLAG( @) 
GENERATE 
GENLVL(15) 
MARGINS (2,72) 
OPTIONS 
SOURCE 
XREF 
Generation Options in Effect 2 | 
NOATTRIBUTES 
NODIAGNOSE 


NODUMP , 
LIST ) 
NOPATCH 


XREF 
NOOPTIMIZE 


A listing of the options (specified explicitly or by default) which were in effect when 
the program was compiled is produced when you specify the *«0PT option in the 
OPTION parameter of the CL command CRTPLIPGM. 


2. 


The options which were in effect for the compilation process. 


Options specifying the debugging aids the compiler can generate. Many of Jo 
them are discussed at “Examples of Using Compiler Debugging Options” on 
page A-10. 


Attribute/Cross Reference Table PLITST/LP1413 12/10/88 11:47:31 Page 4 


LP1413: PROCEDURE; PUBO81686 
Attributes and References 


STATIC /* STRUCTURE */ 
4 FILE RECORD INPUT SEQUENTIAL CONSECUTIVE BUFSIZE(38) 


5,7,9,13,15 j 
FILE RECORD OUTPUT SEQUENTIAL INDEXED KEYLENGTH(10) KEYDISP(@) : ) 
8,12,16 

/* In: INDEX_RECORD */ AUTOMATIC UNALIGNED PICTURE FIXED(8,2) 
/* In: INDEX_RECORD */ AUTOMATIC UNALIGNED CHARACTER(10) 

/* In: INDEX_RECORD */ AUTOMATIC UNALIGNED CHARACTER(26) 
AUTOMATIC /* STRUCTURE */ 

11,12 

/* Ins INPUT_RECORD */ AUTOMATIC UNALIGNED PICTURE FIXED(8,2) 
/* In: INPUT_RECORD */ AUTOMATIC UNALIGNED CHARACTER(10) 

/* In: INPUT_RECORD */ AUTOMATIC UNALIGNED CHARACTER(2@) 
AUTOMATIC /* STRUCTURE */ 

9,11,13 

EXTERNAL ENTRY 

/* Ins BIT_FLAGS */ STATIC ALIGNED BIT(1) 

6,10 

5 

/* In: BIT_FLAGS */ STATIC ALIGNED BIT(1) INITIAL 

5 

/* Ins BIT_FLAGS */ STATIC ALIGNED BIT(1) INITIAL 

6 


To produce a cross-reference listing of all of the variables in your program, specify J 
the «XREF option in the OPTION parameter of the CL CRTPLIPGM command. 
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Ss 


COMPILER OUTPUT 


Statement numbers for the declarations of each of the variables. 


When a data item is declared as part of a multiple declaration, both the state- 
ment and substatement where the item is declared are specified. 


The identifiers used in the program (including names of procedures, files, and 
structures). 


Attributes of each of the items and the numbers of the statements in which 
each item is referenced. Since the CRTPLIPGM command specifies *ATR as an 
option of the OPTION parameter, the attributes of each item declared in the 
program are also listed. If you specify both «XREF and «ATR, the compiler 
produces a combined cross-reference and attribute table; but you can specify 
one or the other and obtain a list of statements declaring and referencing the 
variables, or a list of the attributes of each item declared. 


5728PL1 R61 M66 880715 PL/I Aggregate Length Table PLITST/LP1413 11/30/88 15:51:24 Page 6 
LP1413: PROCEDURE; PUBOO166 
STMT. SUBS Identifier LVL DIMS Offset From Major Element Length Aggregate Length 
4 BIT FLAGS ff] 1 3 
MORE_RECORDS 2 0{1) 
--PADDING-- 2 6(1) 0(7) 
NO 2 1 0(1) 
--PADDING-- 2 1(1) 0(7) 
YES 2 2 Q(1) 
--PADDING-- 2 2(1) 6(7) 
3 INDEX_RECORD 1 38 33 
INDEX_KEY 2 10 
INDEX_NAME 2 ie & 20 
INDEX_BAL 2 36 8 
3.4 A _sINPuT_RECORD 1 38 38 
IHPUT_KEY 2 10 
INPUT_NAME 2 10 20 
INPUT_BAL 2 30 8 


Sum of Constant Lengths - 79 


The aggregate length table is produced when you specify the «AGR option in the 
OPTION parameter of the CRTPLIPGM command. 


BOA FRE WG 


The statement in which the aggregate was declared. 


When an aggregate is declared as part of a multiple declaration, both the 
statement and substatement for the declaration are specified. 


The names of the aggregates and their components. 
The level number of each identifier. 
For arrays, the number of dimensions in the array 1s listed. 


The offset of each element from the first byte of storage occupied by the 
aggregate. 


The length of each element, and each aggregate’s total length. 
The length of each aggregate. 
The total number of bytes occupied by the aggregates. 
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Running the Program 
The most common ways to run a PL/I program are: 


¢ Using the CL command CALL as part of a batch job, entered interactively by 
the work station user, or included in a CL program. 


¢ Using the PL/I statement CALL in a PL/I program (see “CALL Statement” on 
page 14-7). 


¢ Using the other AS/400 language call statements 


¢ Using a menu, from which the user can choose an option that calls the 
program. 


¢ Creating your own command (see the CL Programmer's Guide for information 
on creating your own command.) 


For more information on how to call a compiled program, see the CL. Program- 
mer’'s Guide. 


Interrupting or Ending the Running of a Compiled Program 
You can interrupt or end the running of a compiled PL/I program as follows. 


If you are running the program from a batch job, you should issue the CL command 
ENDBCHJOB (End Batch Job). For information on the ENDBCHJOB 
command, see the Programming: Control Language Reference. 


If you are running the program interactively, press the Sys Req key to interrupt. 
Then press Enter to get the System Request Menu. You then have a choice of 
various options from the System Request Menu. For example, if you want to end 
processing of the program, enter option 2. If you want to resume the processing of 
the program, either press the F3 key, or press Enter with the options field left blank. 


Abnormal Program Ending 
If the processing of a PL/I run unit ends abnormally, escape message PLI9001 or 
PLI9002 or PLI9003 1s sent to the program that called the first procedure in the run 
unit. This results in a function check if the escape message is not monitored. Ina 
CL program, you can monitor these messages with the CL command MONMSG 
(Monitor Message). See the Programming: Control Language Reference for more 
information. 


A program that causes an error that cannot be handled through the normal flow of 
control will set the return code to 4. If the program processes a SIGNAL statement 
for the ERROR condition, the return code is set to 3. The processing of a STOP 
statement or a call to PLIDUMP with the stop option (S) will set the return code 
to 2. For information on return codes, see the entries in the Programming: Control 
Language Reference on the CL commands RTVJOBA (Retrieve Job Attributes) and 
WRKJOB (Work With Job). 
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C 


Interlanguage Calls 


The AS/400 System allows you to call programs written in different languages. The 
techniques used for transferring between programs and passing parameters are 
similar to those used for communicating between different programs written in PL/I. 
There are two cases to consider: 


¢ When your PL/I program calls a program written in another language 
e When a program written in another language calls your PL/I program. 


Calling a Non-PL/!I Program 
In a calling PL/I program, you must code an ENTRY declaration for the program you 
will link to. For example: 


DECLARE COBOLPGM ENTRY 
C (CHARACTER (8), 
FIXED DECIMAL (4,1), 
FIXED DECIMAL (3)), 
OPTIONS (ASSEMBLER) ; 


The OPTIONS (ASSEMBLER) attribute tells the compiler that the interface with 
the called program will be at the machine interface level: that is, that PL/I will pass 
parameters directly to the program instead of using PL/I control blocks. 


Arrays are not supported as parameters between PL/I and BASIC, because PL/I does 
( not build the array descriptors which BASIC requires for arrays. 


After the ENTRY attribute, you should list t’ . attributes (not the variable names) 
of the parameters passed to the called program. 


When you call a non-PL/I program, you list the variables that you are using as 
parameters. These variables must be declared with exactly the same attributes as 
those you have listed in the ENTRY declaration. For the ENTRY declaration 
given above, you may declare the parameter variables as follows: 
C DECLARE ITEM1 CHARACTER (8), 

ITEM2 FIXED DECIMAL (4,1), 
RESULT FIXED DECIMAL (3); 


You would then initialize the variables for which you wish to pass a value to the 
program you are calling: 

GET FILE (SYSIN) EDIT (ITEM1,ITEM2) (A(8),F(4,1)); 

The actual CALL statement has the same format as for the calling of a PL/I 
procedure: 

CALL COBOLPGM (ITEM1,ITEM2,RESULT); 


Control is passed to COBOLPGM, which could use ITEM1 and ITEM2 as input 
data and place a value in RESULT that will be returned to the calling PL/I program. 


When the called program finishes running, control is returned to the statement fol- 
: lowing the call statement. 
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If a non-PL/I program ends abnormally, the ERROR condition is raised in the 
calling program. You can use an on-unit to take appropriate action. 


Calling a PL/I Program from a Non-PL/I Program 


In a PL/I program called by a program that is coded in another language, you must 
list the parameters in the PROCEDURE statement at the start of the program: 


SUBPGM: PROCEDURE (INTEGER1, INTEGER2,CHAR1) ; 


The parameter variables must be declared inside the PL/I program: 


DECLARE INTEGER] FIXED BINARY (15), 
INTEGER2 FIXED DECIMAL (7), 
CHAR1 CHARACTER (8); 


The attributes of the parameter variables declared in the PL/I program must exactly 
match the attributes in the calling program. You cannot use asterisks or variables to 
indicate the length of a character or bit scalar data item, or the bounds of an array, 
as in: 


DECLARE CHARITEM CHARACTER (+), 
ARRAY1(INDEX1) FIXED DECIMAL (7), 
BITARRAY («) BIT (*) ALIGNED; 


The necessary PL/I control blocks which furnish these values when the program is 
called are available only when the calling program is written in PL/I. 


When a floating-point value is passed to a PL/I program from CL, the variable that 
the data is placed in must have the UNALIGNED attribute in the PL/I program. 


The following tables show you how to code matching data types in PL/I and the 
other languages available on the AS/400 System. 


Daan [PLR RPG 


FIXED DECIMAL (p,q) Columns 


Packed 
Decimal 


Where: 


6 


p = total number of digits 43 
and 1<p<15. 44-47 a, where b-a+1 = 


q = number of digits to the (p+1)/2 and l<p<15 
right of the decimal point 48-51 b 
and l<q<15. 52 q, where q is the 
p = greater than or equal to q number of decimal 
digits 
name of the packed 
field 


Figure 2-7 (Part 1 of 3). Matching PL/I Attributes in RPG 
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Zoned PICTURE 'p' 
a Where: 
p is the number of 9s 
- or - 
PICTURE 'pVq' 
Where: 
p is the number of 9s to the 
left of the V and 1<p<15 
V is the implied decimal point 
q is the number of 9s to the 
right of the V and 1<q<15 
p is greater than or equal to q 


Fixed FIXED BINARY (p) Columns 
ae Where: : 
p = total number of binary 43 
digits and 1<p<31 


Float FLOAT DECIMAL (p) 
pecuna! Where: 
p = total number of digits 
and 1<p<16 
Float FLOAT BINARY (p) 
pny Where: 
p = total number of digits 
and 1<p<53 


Figure 2-7 (Part 2 of 3). Matching PL/I Attributes in RPG 
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Code 


I 

blank 

a, where a 1s the 
starting position of 
the field 

b, where b is the end 
position of the field 
q, where q is the 
number of decimal 
digits and 0<q<9 
name of the zoned 
subfield 


a, where ais the 
starting position of 
the field 

b, where b is the end 
position of the field 
q, where q is the 
number of decimal 
digits and 0<q<9 
name of the binary 
subfield 


Not supported. 


Not supported. 
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Dare [PU 


BIT (w) The use of bit strings is not sup- 
Where: ported. A bit string can be passed 
Character CHARACTER (w) 
~ ro 
= total number of charac- 
ters and l<w<32 767 


as a character string in which the 
w = total number of bits and length of the character string in 
l<w<32 767 bytes is equal to (w + 7)/8. The 
Varying CHARACTER (w) Not supported. 
Length VARYING 
Character | 
| Where: 


receiving program must define the 
bits in the bytes being passed. 


Code 


Columns 


28-32 PARM 
49-51 w, where 1<w<999 


w = total number of charac- 
ters and l<w<32 765 


Figure 2-7 (Part 3 of 3). Matching PL/I Attributes in RPG 


PIC S9(p)V9(q) DECLARE PROGRAM | TYPE(*DEC) LEN(p q) 
USAGE COMP-3 .. PD p.g 


Where: Where: 


I<p<15 I<p<15 
I<q<l5 I<q<l15 


-or- -or- 


PIC S9(p) USAGE 
COMP-3 


Where: 


l<p<15 
q=0 


DECLARE PROGRAM 
.. PD p 


Where: 


l<p<15 
q=0 


Figure 2-8 (Part 1 of 3). Matching PL/I Attributes in COBOL, BASIC, and CL 
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Zoned PIC S9(p)V9(q) DECLARE PROGRAM || Not supported. 
Decimal 


USAGE DISPLAY .. LD p.q 
Where: Where: 


p=15 l<p<15 
l<q<15 l<q<15 


- OF - - OF - 


DECLARE PROGRAM 
.. ZD p 


Where: 


l<p<15 
q=0 


PIC $9(p) 
USAGE DISPLAY 


Where: 
l<psl5 


Fixed PIC §9(4) USAGE INTEGER Not supported. 
Binary COMP-4 Where: 
Where: l<p<15 
l<p<15 see 
- or - 
DECLARE PROGRAM 
CC PIC 89(9) USAGE . B2 
nee Where: 
Where: I<p<5 
I<p<15 
Float Not supported. DECIMAL A floating-point literal 
Decimal with double precision 


Where: 
Where: 


, l<p<6 
' l<p<6 
- Or - 


DECLARE PROGRAM 
ao 


Where: 


l<p<7 


Figure 2-8 (Part 2 of 3). Matching PL/I Attributes in COBOL, BASIC, and CL 
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A floating-point literal 
with double precision 


Float Not supported. DECIMAL 
Binary Where: 
p>24 
-or- 
3 
Where: 
[<p<24 


The use of bit 
strings is not sup- 
ported. A bit string 
can be passed as a 
character string in 
which the length of 
the character string 
in bytes is equal to 
(w + 7)/8. The 
receiving program 
must define the bits 
in the bytes being 
passed. 


PICTURE X(w) 
Where: 
l<w<32 767 


Character 


01 name-1. 
02 name-2 PIC 


Varying 
Length 
Character 


02 name-3 PIC 

X(w) OCCURS 
DEPENDING 
ON name-2. 


Where: 
l<w<9 999 


59999 COMP-4. 


DECLARE PROGRAM 


The use of bit strings is 
not supported. A bit 
string can be passed as a 
character string in which 
the length of the char- 
acter string in bytes is 
equal to (w + 7)/8. The 
receiving program must 
define the bits in the 
bytes being passed. 


. Cw 
Where: 
I<w<255 


ww WV 
Where: 
l<w<255 


DECLARE PROGRAM 


DECLARE PROGRAM 


Where: 
l<p<24 


The use of bit strings is 
not supported. A bit 
string can be passed as a 
character string in which 
the length of the char- 
acter string in bytes is 
equal to (w + 7)/8. The 
receiving program must 
define the bits in the 
bytes being passed. 


TYPE(+CHAR) 
LEN(w) 


Where: 
l<w<2 000 
Not supported. 


Figure 2-8 (Part 3 of 3). Matching PL/I Attributes in COBOL, BASIC, and CL 
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MESSAGES 


Chapter 3. Testing and Debugging PL/I Programs 


Both OS/400 and PL/I offer features that you can use to test and debug your PL/I 
programs. 


OS/400 provides: 


¢ Test library 

¢ Breakpoints 

e Traces 

¢ A debug feature. 


PL/I provides: 


¢ PLIDUMP 

e An error dump option screen 
¢ PLIIOFDB 

e PLIOPNFDB 

¢ ON conditions. 


Note: Some of these PL/I features may use OS/400 functions to provide input. 
The OS/400 features let you test programs while protecting your production files, 


and let you observe and debug operations as a program runs. No special source 
code is required to use the OS/400 features. 


The PL/I features can be used independently of the OS/400 functions or in combina- 
tion with them to: 

¢ Debug a program 

¢ Produce a formatted dump of the contents of fields, data structures, arrays, and 


tables. 


Source code in the form of compiler directives is required to use the PL/I debugging 
features and formatted dump. 


Using, Displaying, and Printing Messages 


This manual refers to messages you receive from the compiler. These messages are 
displayed on your screen or printed on your compiler listing. There are no message 
manuals for this product. 
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MESSAGES 


Each compiler message contains a minimum of three parts as illustrated in the fol- 
lowing screen example: 


MSGID: PLC21B8 Severity: 20 
Message : An unexpected continuation was found. An 
end of statement is assumed before 'PUT SKIP EDIT ( A’. 
This text cannot be interpreted as a 


continuation of the statement. A delimiter, such as an 

operator in the expression or a semicolon may be missing. 

The compiler ignores the text up to the next semicolon. 
Recovery ... 3: Check for a missing delimiter. 


EY A number indicating the severity of the error. 


Severity 
00 


10 


20 


30 


40 


50 


99 


Meaning 


An informational message displayed during entering, compiling, and 
running: This level is used to convey information to the user. No error 
has been detected and no corrective action is necessary. 


A warning message displayed during entering, compiling and running: 
This level indicates that an error was detected but is not severe enough 
to interfere with the running of the program. The results of the opera- 
tion are assumed successful. 


An error message displayed during compiling: This level indicates that 
an error was made, but the compiler is taking a recovery that might yield 
the desired code. The program may not work as the author intended. 


A severe error message displayed during compiling: This level indicates 
that an error too severe for automatic recovery was detected. Compila- 
tion is completed, but running the program cannot be attempted. 


An abnormal end of program or function message displayed during 
running: This level indicates an error that forces cancellation of proc- 
essing. The operation may have ended because it was unable to handle 
valid data, or possibly because the user cancelled it. 


An abnormal end of job message displayed during running: This level 
indicates an error that forces cancellation of job. The job may have 
ended because a function failed to perform as required, or possibly 
because the user cancelled it. 


A user action taken during running: This level indicates that some 
manual action is required of the operator, such as entering a reply, 
changing diskettes, or changing printer forms. 


[:] The text you see online or on a listing. This text is a brief, generally one sen- 
tence, description of the problem. 


The text you see online when you press F4 from the screen with the first-level 
text. This text will be printed on your listing if you specify *SECLVL in your 
compile-time options. The IBM-supplied default for this option is *NOSECLVL. This 
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text contains an expanded description of the message (Cause) and a section detailing 
the correct user response (Recovery). 


Displaying and Printing Messages 


To display or print a particular message or messages, use the DSPMSGEF or 
DSPMSGD commands. These commands are described in the Programming: 
Control Language Reference. 


Note: If you have any comments or suggestions concerning the messages, please use 
the Reader Comment Form included with this manual and send them to us. 


Using a Test Library 


Programs that run in a normal operating environment can read, update, and write 
records in both test and production libraries. Programs that run in a testing envi- 
ronment can also read, update, and write records in both test and production 
libraries. However, to prevent data base files in production libraries from being 
accidentally changed, you can use UPDPROD(«NO) in the CL command STRDBG 
(Start Debug) or in the CL command CHGDBG (Change Debug). See the Pro- 
gramming: Control Language Programmer's Guide and the Programming: Control 
Language Reference for more information. 


On the AS/400 System, you can copy production files into a test library or you can 
create special files for testing in the test library. A production file and its test copy 
can have the same name if they are in different libraries. You can then use the same 
file name in the program for either testing or normal processing. 


Normal Operating Environment 


Production Library 


Production Files 


Debug Environment 


Test Library 


Test Files «—(copy) 


Figure 3-1. Using a Test Library 


For testing, you must put the test library name ahead of the production library 
name in the library list for the job that contains the program tested. For normal 
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processing, the test library should not be named in the library list for the job, as J 
shown in the following diagram. 


Debugging 
TESTLIB 
Library List 
TESTLIB 
Program PRODLIB1 PRODLIB1 J 


PRODLIB2 
QTEMP 


PRODLIB2 


Normal Operating Environment 


Library List PRODLIB1 


c 


PRODLIB1 
Program PRODLIB2 


QTEMP 


PRODLIB2 


Figure 3-2. Using a Library List 


No special statements for testing are necessary within the program being tested. The 

program can be run normally without any changes. All debug functions are given in 
the job that contains the program instead of in the program. However, you can J 
include statements such as CALL PLIDUMP in your program if you need them. 
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Debug Functions +—__—_———_———These functions are given 
through CL commands. 


Programs 


Figure 3-3. Using Debug Functions 


Debug functions apply only to the job in which they are given. A program can be 
used at the same time in two jobs: one job that is in a testing environment, and 
another job that is in a normal operating environment. 


Using Breakpoints 


A breakpoint is a point in your program where you want the program to stop 
running and wait. You can use any of the following as a breakpoint: 


¢ A statement number from the compiled program source listing. 
¢ A machine interface (MI) instruction number from an IRP program listing. 


You cannot use SEU2 source sequence numbers or labels and procedure names 
from the program. 


When a breakpoint statement is about to be processed in an interactive job, the 
system displays the breakpoint at which the program is stopped. The values of the 
program variables you have asked for on the ADDBKP command, if any, are dis- 
played. After this information is displayed, press F10 to get the command entry 
screen, from which you can enter CL commands to ask for other functions (such as 
displaying or changing a variable value, adding a breakpoint, or adding a trace), or 
press Enter to continue processing, or press F3 to cancel the program or function 
being processed. 


For a batch job, a breakpoint program can be called when a breakpoint is reached 
in the program being tested. The breakpoint information is passed to the break- 
point program. For a description of the actual parameters passed, see the 
description of the BKPPGM parameter of the CL command ADDBKP in the Pro- 
gramming: Control Language Reference. 


Example of Using Breakpoints 
The following CL program calls the program shown in Figure 8-5 on page 8-10, 
adds breakpoints, and displays the values on the screen. 
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5728PW1 ROIMGO 880715 SEU SOURCE LISTING 11/36/88 69:51:06 PAGE 1 

SOURCE FILE. ... 2... PLITST/CL 

MEMBER 2. 2 2 we we eee BREAKPT 

SEQNBR*...teee L ccctene 2 cectace 3 ceeteee 4 sucteee 5 ceetene © coctene 7 cootere 8 ceeteee FI cecteee O 
100 PGM 06/16/83 
200 ENTDBG PGM(LP1414) UPDPROD(*YES) 61/09/85 
306 ADDBKP STMT(18) 63/01/84 
406 ADDBKP STMT(20) PGMVAR((INPUT_KEY)) 63/61/84 
506 CALL PGM{LP1414) 03/01/84 
606 ENDDBG 
760 ENDPGM 66/16/83 


Figure 3-4 (Part 1 of 2). CL Program and Display for Breakpoints 


Display Program Variables 
Program > LP1414 
Invocation level : 
Start position 


@2 INPUT KEY 


CHARACTER 


Press Enter to continue. 
F3=Exit F12=Previous 


Figure 3-4 (Part 2 of 2). CL Program and Display for Breakpoints 


Considerations for Using Breakpoints 
You should be aware of the following before you use breakpoints: 


¢ Ifa breakpoint is bypassed by a PL/I statement, such as GOTO, that Sci 
iS ignored. 


¢ When a breakpoint is added for a statement, the program stops just before the 
statement is processed. 


¢ Breakpoint functions are specified through CL commands. 


These functions include adding breakpoints to programs, displaying breakpoint 
information, removing breakpoints from programs, and continuing to run a 
program after a breakpoint display is shown. See the Programming: Central 
Language Reference for information on these commands, and the Programming: 
Control Language Programmer's Guide for more information about breakpoints. 
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Using a Trace 


A trace 1s a record of some or all of the statements in a compiled program that were 
processed and the values of any variables that were specified on the CL command 
ADDTRC. A trace is different than a breakpoint in that you are not given control 
during the trace. 


The system records the traced statements that were processed. You must ask for a 
display of the traced information using the CL command DSPTRCDTA. The 
display shows the sequence in which the statements were processed and the values 
of variables you specified. 


You enter the statements that the system should trace. You can also specify that 
variables be recorded or displayed before each traced statement is processed, or only 
when the value of some traced variable changes from the last time a traced state- 
ment was processed. 


You can request a trace of one statement in a program, a group of statements in a 
program, or all the statements in a program. 


Example of Using a Trace 


The following CL program adds a trace requests, calls the program shown in 
Figure 8-5 on page 8-10, and displays the trace data. 


5728PW1 RG1MOQ@ 880715 SEU SOURCE LISTING 11/30/88 09:54:53 PAGE 1 

SOURCE: FILE: %. 6 -& & as PLITST/CL 

MEMBER .... se eee TRACE 

SEQNBR* ictosec) 2ee8seu 2 ceases SD awe W Geta S colt OR aihous 7 aacteis BS wertiw 2 ati 8 
100 PGM 66/10/83 
200 ENTDBG PGM(LP1414) UPDPROD(*YES) 01/09/85 
308 ADDTRC STMT((19 23)) PGMVAR((INPUT_KEY)) OUTVAR(*CHG) 03/01/84 
4080 CALL PGM(LP1414) 03/01/84 
500 DSPTRCDTA CLEAR(*YES) 01/09/85 
600 ENDDBG 
700 ENDPGM 06/10/83 


Figure 3-5 (Part 1 of 2). CL Program for Requesting a Trace and Displaying Trace Data 


Chapter 3. Testing and Debugging PL/I Programs 3-7 


USING TRACES 


1/07/88 18:49:50 
Stmt/Inst: 19 
Start pos: 1 
Variable: 02 


TRACE DATA DISPLAY 
Pgm: LP1414 
Lens *DCL 
INPUT_KEY 


Inv lvl: 
Format: 


Type: 


CHARACTER 


D eeT ere decent ease erewet wee co osGe t iewa ew ae ts weed 
'11111 
Stmt/Inst: 
Stmt/Inst: 
Stmt/Inst: 
Stmt/Inst: 
Stmt/Inst: 

Start pos: 1 

*Variable: 02 


LP1414 
LP1414 
LP1414 
LP1414 


INPUT_KEY 
CHARACTER 


'2222211111' 
Stmt /Inst: 20 
Stmt/Inst: 21 
Stmt/Inst: 22 
Stmt/Inst: 23 

Start pos: 1 
*Variable: Q2 


LP1414 
LP1414 
LP1414 
LP1414 
*DCL Format: 


INPUT_KEY 


Figure 3-5 (Part 2 of 2). CL Program for Requesting a Trace and Displaying Trace Data 


Considerations When Using a Trace 
You should be aware of the following before you use traces with PL/I programs: 


¢ Ifa group of PL/I statements is bypassed, they are not included in the trace. 
The case is similar with breakpoints (see “Considerations for Using 
Breakpoints” on page 3-6). 


e Trace functions are given by CL commands in the job that contains the traced 
program. 


These functions include adding trace requests to a program, removing trace 
requests from a program, removing data collected from previous traces, dis- 
playing trace information, and displaying the traces that have been entered for a 
program. 


e In addition to statement numbers, names of routines generated by PL/I can 
appear on the trace output STMT field. 


The compiler reorganizes the source statements in your program by denesting the 
blocks (including procedures). The effect of denesting is illustrated below: 
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Program Source 


PL/I PL/I 
Statement Source 
Number Statement 


1 OUTER: PROCEDURE; 
20 INNER: PROCEDURE; 
50 ITEM1 = ITEM1 + 1; 
60 END INNER; 
70 ITEM2 = ITEM2 + 1; 
100 END OUTER; 


Sequence of MI Instructions Generated in the Source Listing 
When This Source is Compiled 
PL/I PL/I 


Statement Source 
Number Statement 


1 QUTER: PROCEDURE; 
70 ITEM2 = ITEM2 + 1; 
100 END OUTER: 
20 INNER: PROCEDURE; 
50 ITEM! = ITEM] + 1; 
60 END INNER; 


This denesting of blocks has the following consequences: 


¢ You should not specify a trace range where the starting and ending statements 
are contained in different blocks, because the range may not be valid or may 
trace a set of statements different from the one you intended. For example, the 
following CL command would not be valid for the example above: 


ADDTRC STMT((50 70)) 


because statement 50 corresponds to a higher MI instruction number than state- 
ment 70 in the MI program. 


e If you specify a range of statements that includes a nested block, no trace will be 
processed on the statements contained by the inner block. For instance, 


ADDTRC STMT((1 100)) 
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Using Debug 


PL/I Storage 


Calling Levels 


does not trace any of the statements in INNER, because the MI instructions for 
INNER are all beyond the MI instruction for statement 100 in the MI program.: 


You can always specify 
ADDTRC STMT (+ALL) 


to trace all statements processed in the entire program. 


See the Programming: Control Language Programmer's Guide for more information 
about traces. 


OS/400 Debug is used in a test environment that you can enter using CL commands 
like STRDBG (Start Debug) or CHGDBG (Change Debug). This environment 
allows you to use the debugging features and run the program without affecting the 
normal program environment. The following items should be taken into account 
when using debug: 


e Calling Levels 

¢ Scoping of names 

¢ Fully qualified names 

¢ PL/I pointers 

¢ Floating point variables 

e Changing varying length strings 

¢ Specifying variables by ODV number 

¢ Displaying level numbers 

¢ References to static variables 

¢ Determination of active blocks in a program. 


PL/I variables use storage areas allocated and maintained by PL/I. The system 
Program Static Storage Area (PSSA) or the Program Automatic Storage Area (PASA) 
are not used for any PL/I variables. 


When you use a recursive program or procedure, you should be aware of two calling 
levels: the program calling level and the procedure calling level. 


When a program or external procedure is called recursively, the program calling level 
is incremented. You can specify the program calling level on the OS/400 debug 
commands through the INVLVL parameter. 


When an internal procedure is called recursively, the procedure calling level is incre- 
mented. You cannot specify the procedure calling level on the OS/400 debug com- 
mands. Only the last (most recent) procedure calling level is available for 


debugging. 
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Scoping of Names 


In PL/I, the scope of a name is determined by the block(s) in which it is declared. A 
block is defined by a PROCEDURE or BEGIN statement. If a name is declared in 
more than one block in a program, PL/I scoping rules determine which declaration is 
used when you refer to the name. For more information on scoping, see “Names” 
on page 4-12. 


OS/400 debug operates outside of the PL/I program and cannot use PL/I scoping 
rules to determine which declaration you are referring to. When a name is unique 
only because of PL/I scoping rules, debug will not be able to determine which decla- 
ration should be used (a message is issued saying the name is ambiguous). 


To specify a unique reference to a name declared in more than one block, use the 
block number on the compiled program source listing. The block number is the 
highest level qualifier for a name in a PL/I program. That qualifier represents the 
block that the variable is declared in. When you specify the block number that the 
variable is declared in, OS/400 debug can determine which declaration of a name 
should be used. 


The qualifier is of the form «BLKn, where n is a one to three digit block number. 


For example, if variable K is defined in blocks 2 and 5 in your program, and you 
wish to display the value of K in block 5, specify a PGMVAR parameter of 
*BLK5.K. If block 5 is not currently active, the value of K in block 5 cannot be 
displayed: instead, a message is displayed that indicates that the variable is not cur- 
rently active. Note that the value of K in block 5 is displayed even if block 2 is also 
active. 


Fully Qualified Names 


The test environment recognizes a concept of a fully qualified name similar to the 
PL/I concept. However, because every PL/I variable has a block number as the 
highest level qualifier, you must specify the block number qualifier (+BLKn) as a 
part of the fully qualified name, whenever it is necessary to specify the fully qualified 
name. For example, consider the following declarations: 


DECLARE 1 SAMPLESTRUCTURE, 
5 ITEM1 FIXED BINARY (15); 
DECLARE ITEM1 CHARACTER (10); 


A request to display or change ITEM] is ambiguous to the OS/400 debug facility. 
Assuming the variables are both in block 7, you must specify 


*BLK7.SAMPLESTRUCTURE. ITEM1 


Or 
SAMPLESTRUCTURE. ITEM1 


to process the variable ITEM1 that is an element of SAMPLESTRUCTURE, and 
*BLK7.ITEM1 


to process the scalar character variable ITEM1. 
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PL/I Pointers 
Names that are declared with the POINTER attribute in the PL/I source program 
are called High Level Language (HLL) pointers in the test environment. These 
pointers are maintained at the machine level as space pointers. You can. only 
change them in the test environment using the CL command CHGHLLPTR 
(Change High Level Language Pointer) or CHGPTR (Change Pointer) to contain a 
space pointer value or a null pointer. 


The CHGHLLPTR command allows you to change the value of a HLL pointer. 
This pointer can be a pointer variable or a basing-pointer name. The value of the 
pointer copied can be a pointer variable or a program variable address referred to by 
the variable name. The reference pointer or program variable can have another HLL 
pointer(s) specified as its basing pointer(s). 


The following CL statements illustrate the use of the command: 
CHGHLLPTR PTR('PTR1') REFPTR('PTR2') 


CHGHLLPTR PTR('PTR3(4)') ADR('VARI(VAR2,5)' 'PTR4(3)') 


For more information on the CL command CHGHLLPTR, see the Programming: 
Control Language Reference. 


Floating Point Variables 
In the test environment, floating point variables are displayed with the precision in 
which they are stored internally, and not as they are declared in your PL/I program. 
Short floating point variables are displayed with a precision of BINARY 
FLOAT(24) or DECIMAL FLOAT (7), which requires four bytes of storage. 
Long floating-point variables are displayed with a precision of BINARY 
FLOAT(53) or DECIMAL FLOAT (16), which requires eight bytes of storage. 
OS/400 debug does not use the value of the precision declared in the program before 
displaying or changing the value. 


Changing Varying Length Strings 
When you use the CL command CHGPGMVAR to change a varying length char- 
acter string, the bytes changed must either start within the current length of the 
string or start at the next byte after the end of the string as defined by the current 
length. If the current length is negative, the length is treated as though it were 0. 
The length of the string is always adjusted to match the last byte changed by the 
command. If updating the variable exceeds the maximum length, an error message 
is issued and the variable is not changed. 


A varying-length s.ring can be truncated without changing the value in the part of 
the string that remains after truncation. To do this, specify a null string for the new 
value. For example: 


CHGPGMVAR PGMVAR(VARYINGCHARSTRING) VALUE(' ') START(11) 


truncates the current length of VARYINGCHARSTRING to ten characters. The 
byte count at the start of the string is updated to a value of ten. 
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Specifying Variables by ODV Number 
You can display and change program data using ODV (Object Definition Table 
Directory Vector) numbers. These numbers are found on the program IRP listing, 
which is obtained by specifying GENOPT («LIST) on the CRTPLIPGM 
command. A cross-reference of oDV numbers can be obtained by specifying 
GENOPT(«XREF) on the CRTPLIPGM command. For more information on 
the format of ODV numbers, refer to the Programming: Control Language Prograrn- 
mer’s Guide. 


If ODV numbers are used to specify the names of variables, OS/400 debug only uses 

the information that is defined for the variable at the machine instruction (MI) inter- 
face. The value and attributes of the variable presented to you may be very different 
from what would be presented if the HLL variable name was specified. 


Displaying Level Numbers 
Any PL/I variable declared with a structure level number is shown on the OS/400 
debug display with the level number immediately preceding the variable name. The 
level numbers displayed by OS/400 debug start at 1 for each structure and increment 
by | for each new level in the structure. The following example shows the level 
numbers for a structure in a PL/I program, and the corresponding level numbers that 
would be displayed by OS/400 debug. 


PL/I OS/400 
Level Level 
Number Number 
01 PARTS, 01 
05 ITEM, 02 
10 OLO FIXED DECIMAL (5,0), 03 
10 NEW FIXED DECIMAL (9,0), 03 
05 DESCRIPT CHAR(10); 02 


References to Static Variables 
A variable declared in your PL/I program with the STATIC attribute can only be 
referenced by OS/400 debug when the program and block in which it is declared are 
currently active. 


Determination of Active Blocks in a Program 
A variable can only be displayed or changed by OS/400 debug if the block that 
defined the variable is active. This is true regardless of the storage class of the vari- 
able. You can determine if a block is active at any point while debugging by dis- 
playing any variable that is declared in the block, or by displaying the special 
variable *BLKn where n ts the block number that you want to check. If you 
receive a message that the variable is not active, the block is not currently active. 
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Using PLIDUMP 


The PLIDUMP built-in subroutine produces a symbolic dump of the variables of 
the currently running program. The output of PLIDUMP appears on the system 
dump file QPPGMDMP. 


The program variables that are dumped depend on the options you specify when 
you call PLIDUMP. The dump also contains: 


° A list of any ONCODE, ONFILE, or ONKEY data which is relevant 
¢ The date and time of the dump 
¢ The statement number from which the dump was called. 


b>—CALL—PLI wae ale ci 
(‘options_list ia (eee Ii 
user_identification 


options_list 
A contiguous string of characters consisting of one or more of the following 
dump options. 


TNT FNFVNVHNHSC 


The dump options are described as follows. The default dump options are 
underlined. 


Tt Displays a trace of the currently active blocks in the run unit, containing 
the name of the blocks (if applicable), statement numbers of calling state- 
ments, and error information for on-units. 


NT No trace information is displayed. 


es) 


Displays the symbolic attributes and record contents of the buffers of all 
open files. 


NF No file information is displayed. 


Generates a dump of all AUTOMATIC and STATIC variables (with a 
non-zero length) for the current calling of the external procedure with 
their identifiers. Recursive procedures and ON units are dumped for 
only the most recent call. 


I< 


NV No variables are dumped. 


en 


Produces a hexadecimal dump of the PL/I data spaces of the environment 
in which the program is running. This option is provided to assist in 
servicing the program. 


NH _ No hexadecimal dump is produced. 


IN 


Continues running the program after the dump. 


S Ends the program after the dump. When you select this option, an 
“Operator Requested Error Dump” will not be produced (see ‘Error 
Dump Option Screen” on page 3-16 for more information). 
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Options are read from left to right. Invalid options are ignored, and if contra- 
dictory options are coded, the rightmost options are used. 


user_identification 
A character string variable or constant chosen by the PL/I programmer. It can 
be of any length, but a maximum of 36 characters is printed at the head of the 
formatted dump. The rest is truncated. If the character string is omitted, no 
identification is printed. 


When you are debugging, you may call PLIDUMP from an on-unit, however, it 
may be called from anywhere else in your program. 


You can specify the C (continuation) option of PLIDUMP to get a series of dumps 
of storage while the program is running. 


If you call PLIDUMP several times in a program, use a different user identification 
to identify each dump. 


PLIDUMF can also be called whenever the program encounters a system error that 
is not handled by OS/400 or by your program (see the following section). 


Example of Using PLIDUMP 


The program used for the dump in Figure 3-6 is the same as that shown in 
Figure 8-5 on page 8-10, except that the following statement has been added to the 
program between statements 23 and 24: 


CALL PLIDUMP; 
This procedure produces the default dump as shown in Figure 3-6. 


To produce the maximum amount of information, including a variable dump and 
hexadecimal dump, use the following statement: 


CALL PLIDUMP('TFVHC','FULL PL/I PROGRAM DUMP'); 


18:62:28 61/07/88 PLIDUMP CALLED FROM STATEMENT 06825 PROGRAM LP1427. 


CURRENT OPTIONS IN EFFECT (TFNVNHC) 


TRACE 

FILE 
NOVARIABLES 
NOHEXADECI MAL 
CONTINUE 


Figure 3-6 (Part 1 of 3). PL/I program calling PLIDUMP 
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ERROR DUMP OPTION SCREEN 


TRACE OF CURRENT DSA STACK 


DSA BLOCK NUMBER 60001 
BLOCK NAME LP1427 


FROM STATEMENT EXT 
PROGRAM NAME LP1427 


END OF DSA TRACE 


Figure 3-6 (Part 2 of 3). PL/I program calling PLIDUMP 


SYMBOLIC DUMP OF FILE SYSPRINT 


PY] 
STATUS OPEN J 


ACTUAL FILE NAME QPRINT 
SEPARATE INDICATORS NO 
LAST OPERATION PUT 


COMPLETED FILE ATTRIBUTES 
STREAM 
PRINT 
OUTPUT 
EXTERNAL 


ENVIRONMENTAL ATTRIBUTES 


CONSECUTIVE ; 


OUTPUT BUFFER 
600000 40F8F8F8 F8F8F2F2 F2F2F248 46404046 D2D9E8E3 D6D54009 C9404040 40484046 * 8888822222 KYRTON II 
ee0020 40404040 40404040 40404040 40404040 F24BF4F@ 40404048 40404040 40404040 * 2.48 
@00046- 40404048 40404046 40404040 40404046 40404040 40404040 40404040 40404040 * 
800068 SAME AS ABOVE 
900088 40404046 


Figure 3-6 (Part 3 of 3). PL/I program calling PLIDUMP 


J 


Error Dump Option Screen 


When your program encounters a system error that is not handled by OS/400 or by 
PL/I, the following display appears on your work station screen: 
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1/07/88 19:21:28 PROGRAM MESSAGES 
Job J19.QSECOFR.060929 started 01/07/88 19:20:31 in subsystem QGPL/QINTER 
UNDEFINEDFILE condition raised at statement 16 in LP1414 for file MST_FILE. 
ERROR condition raised as a default action at statement 16 in LP1414. ONCODE 
No error on-unit existed in LP1414. Select dump option. (C D F) 


Figure 3-7. Error Dump Option Screen 


To request a dump on the display, enter a D or F; the default is D. The output is on 
the system-wide dump file QPPGMDMP. The response D produces the same dump 
data as the PLIDUMP options T (trace), F (file information), and V (variables). 

The response F provides the same information as response D, and also produces a 
hexadecimal dump of the PL/I data spaces in which the program is running. The 
dump is the same as that produced by option H of PLIDUMP. 


To cancel a dump, enter response C. 


Using PLIIOFDB and PLIOPNFDB 


You can obtain the contents of the system-defined input/output feedback area and 
the system-defined open feedback area by using the PLIIOFDB and PLIOPNFDB 
built-in subroutines. For a description of these subroutines, and a discussion of 
how to use them, see “PLITOFDB Built-In Subroutine” on page 15-16 and 
“PLIOPNFDB Built-In Subroutine” on page 15-17. 


Using ON Conditions 


You can write your programs using specifiable ON conditions to monitor for prob- 
lems you may encounter. ON conditions and condition codes are described in 
Appendix D, “Conditions and Condition Codes,” and their use is discussed in 
Chapter 10, “Condition Handling Statements.” 


The figure below illustrates how you can use ON conditions in your program to 
alert you of problems. 
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5728PW1 RO1MO6 8886715 


SEU SOURCE LISTING 


SOURCE FILE. .....-. PLITST/PLISRC 


MEMBER 
SEQNBR® aa%ees- 1 nati 2 avistees 3 cevtive @ 2¥iece 5 ode Peas GB uccties 7 a 


106 

206 

380 

460 

500 

606 

708 

860 

900 
1066 
1106 
1200 
1360 
1408 
1500 
1680 
1766 
1808 
1908 
2000 
2100 
2200 
2300 
2406 
2500 
2600 
2700 
2800 
2908 
3008 
3106 
3206 
3366 
3400 
3506 
3660 
3706 
3800 
3986 
4060 
4106 
4260 
4308 
4400 
4500 
4660 
4700 
4860 
4900 
5606 
5160 
5208 
5306 


Figure 


3-18 


~ eo ee eo we e)~©6ONCONDSEG f 


‘ON ERROR‘ CONDITION 


DECLARE ONCODE BUILTIN; 


ON ERROR 
BEGIN; 
ON ERROR SYSTEM; 
PUT FILE (SYSPRINT) SKIP(2) EDIT('** ERROR DETECTED **')(X(16),A); 
PUT FILE (SYSPRINT) SKIP EDIT('THE CONDITION CODE WAS ',ONCODE) 
(X(13),A,F(4)); 
END; /* BEGIN */ 


DECLARE 
1 BIT_FLAGS STATIC, 
2 MORE_RECORDS BIT(1) ALIGNED, 
2 NO BIT(1) ALIGNED INIT(‘@'B), 
2 YES BIT(1) ALIGNED INIT('1'B); 


ON ENDFILE (IN_FILE) 
MORE_RECORDS = NO; 


MORE_RECORDS = YES; 
READ FILE (IN_FILE) INTO (INPUT RECORD); 


DECLARE PAGE_NUMBER BINARY FIXED(2); 


PAGE_NUMBER = 1; 


ON ENDPAGE (SYSPRINT) 
3-8 (Part 1 of 3). Examples of ON conditions 
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PAGE 


1 


5728PW 
SOURCE 
MEMBER 


SEQNBR*...+..- 1 cootees 2 coePoee 3 evotees 4 coetene 5 eeetece 6 coeteee 7 cootece 8 eoePeee 9 eve tere ) 


5460 
5500 
5608 
5766 
5800 
5968 
6600 
61060 
6200 
6300 
6400 
6500 
6600 
6760 
6806 
6966 
7660 
7160 
7200 
7300 
7400 
7500 
7606 
7768 
7806 
7908 
8600 
8160 
8200 
8360 
8400 
8560 
8660 
8766 
8866 
8906 
9660 
9166 
9260 
9306 
9466 
9506 
9600 
9768 
9860 
9966 
16668 
10160 
16260 
10360 
16406 
16566 
16666 


Figure 


1 RO1M66 888715 SEU SOURCE LISTING 
FILE. . ~~ « «© - PLITST/PLISRC 
ee © eo © «© © © )©6ONCONDSEG 


BEGIN; 
PUT FILE (SYSPRINT) PAGE EDIT('PAGE ',PAGE_NUMBER) (X(81),A,F(2)); 
PUT FILE (SYSPRINT) SKIP(2) EDIT('UPDATE REPORT') (X(38),A); 
PUT FILE (SYSPRINT) SKIP(2) EDIT('KEY ID','NAME','CUR BALANCE’, 
"UPDATE AMOUNT', 'NEW BALANCE') (A,X(9),A,X(21) ,A,X(6),A,X(4),A); 
PAGE_NUMBER = PAGE_NUMBER + 1; 
END; /* BEGIN */ 


DECLARE ONCODE BUILTIN; 


ON KEY (MST_FILE) 
BEGIN; 
ON ERROR SYSTEM; 
PUT FILE (SYSPRINT) SKIP(2) EDIT(‘'** ERROR DETECTED **') (X(16),A); 
PUT FILE (SYSPRINT) SKIP EDIT('INVALID OPERATION INVOLVING KEY OF', 
' MST_FILE. CONDITION CODE WAS ',ONCODE) (X(13),A,A,F(4)); 
END; /* BEGIN */ 


DECLARE ONCODE BUILTIN; 


ON TRANSMIT (MST_FILE) 

BEGIN; 
ON ERROR SYSTEM; 
PUT FILE (SYSPRINT) SKIP(2) EDIT(‘** UNEXPECTED ERROR ON 1/0 ', 

OPERATION OF MST_FILE')(X(16),A,A); 
PUT FILE (SYSPRINT) SKIP EDIT(‘THE FILE STATUS WAS ',ONCODE) 
(X(13),A,F(4)); 
END; /* BEGIN */ 


"ON UNDEFINEDFILE’ CONDITION (ALSO 'ON UNDF‘) 
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5728PW1 RO1MOG 880715 SEU SOURCE LISTING 11/30/87 10:24:49 PAGE 3 
SOURCE FILE. .....-. PLITST/PLISRC 
MEMBER . . 2... eee - ONCONDSEG 


SEQNBR* siete Dac teee 2 cates SD aeitine Asti 5S wot ie bestia seties Bo hasteve Bias. tie 8 
10880 DECLARE ONCODE BUILTIN; 
19900 . 


11200 ON UNDEFINEDFILE (IN_FILE) 
11300 BEGIN; 


11400 ON ERROR SYSTEM; 

11500 PUT FILE (SYSPRINT) SKIP(2) EDIT('** UNEXPECTED ERROR, UNDEFINED ', 
11600 ‘FILE CONDITION RAISED ON OPENING OF IN FILE')(X(10),A,A); 
11706 PUT FILE (SYSPRINT) SKIP EDIT('THE CONDITION CODE WAS ‘,ONCODE) 
11800 (X(13),A,F(4)); 

11900 END; /* BEGIN */ 

12008 . 

12100 

12206 

12300 

12400 -2-nn nnn nnn nn nnn nn nnn nnn wren ee nnn nnn enn ene nen ene nn eee n nescence ceceee 


Figure 3-8 (Part 3 of 3). Examples of ON conditions 
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Part 2. Reference 


The user’s guide provides you with information on entering AS/400 PL/I programs, 
compiling and running these programs and finding errors in them. The reference 
information in Part 2 is provided if you need specific detailed information on PL/I 
compiler directives, references, expressions, statements, procedures, functions, sub- 
routines, and pseudovariables. 
The reference information is arranged as follows: 

¢ Chapter 4, “Program Elements and Organization” 

¢ Chapter 5, “PL/I Data Organization and Use” 

¢ Chapter 6, “AS/400 PL/I File and Record Management” 

¢ Chapter 7, “File Declaration and Input/Output” 

e Chapter 8, “Using AS/400 Files” 

¢ Chapter 9, “References and Expressions” 

¢ Chapter 10, “Condition Handling Statements” 

e Chapter 11, “Input and Output Statements” 

¢ Chapter 12, “Declaring Names and Attributes of Variables” 

e Chapter 13, “General PL/I Statements” 

¢ Chapter 14, “Procedures, Subroutines, and Functions” 


¢ Chapter 15, “Built-In Functions, Subroutines, and Pseudovariables.” 
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PL/I PROGRAM STRUCTURE 


Chapter 4. Program Elements and Organization 


This chapter gives information on: 
¢ PL/I statements and how to combine them into larger units: 


— Compound statements, 
— Do-groups 
— Blocks. 


¢ The different types of blocks and how to combine them into a PL/I program. 


e Names and how to declare and use them. 


Characters That are Used in PL/I 
C AS/400 PL/I uses the standard PL/I character set. A complete listing of the character 
set can be found in ‘“EBCDIC Codes” on page B-15. Note that in AS/400 PL/I, 
you can use lowercase characters when creating a source program. The lowercase 
character is equivalent to its corresponding uppercase character except when used in 
comments and character literals. 


PL/I Program Structure 


C A PL/I program is constructed from basic program elements called statements and 
directives. There can be up to 9999 statements in a program and up to 9999 sub- 

statements in a statement. There are two types of statements: simple and com- 
pound. Statements make up larger program elements called do-groups and blocks. 


Statements and Directives 
PL/I statements and directives are groupings of identifiers, constants, and delimiters. 
The syntax is: 


Cc simple_statement 


compound statement 


directive 


Statement Labels 


A label is an identifier that names a statement so that it can be referred to at some 
other point in the program. Statement labels are either label constants or entry con- 
stants (see “LABEL Attribute” on page 12-31 and “ENTRY Attribute” on 


page 12-32). 

The descriptions of individual statements do not generally include the label. You 

can use a label for any statement unless it is explicitly stated that you cannot use 
Cc one. 
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It is a good idea to use labels following the IF, THEN, ELSE, WHEN, and OTH- 
ERWISE keywords to make the program easy to read. The following example 
shows the format you should use: 


IF REMAINING ITEMS = 0 
THEN 
CASE1: SIGNAL FINISH; 
ELSE 
CASE2: CALL NEXT_ITEM 


Note: You cannot use a label with a compiler directive. 


Simple Statements 


There are three types of simple statements: keyword, assignment, and null. Each 
type ends with a semicolon. 


A keyword statement begins with a keyword that indicates the function of the state- 
ment. For example: 


READ FILE (INFILE) INTO (CURRENT RECORD); 


The assignment statement contains the assignment symbol (=). The statement 
does not begin with a keyword. For example: 


A=B+C; 


The null statement consists of a semicolon and may contain a label. For example: 
LABEL: ; 


Directives 
A directive consists of a % sign (or, optionally, an « for the % PROCESS directive) 
followed by an instruction to the compiler. Each directive ends with a semicolon. 


Labels are not allowed on directives. Directives are discussed in “Using Compiler 
Directives” on page 2-16. 


Elements of a PL/I Statement 
A PL/I statement consists of constants, identifiers, and delimiters. 


Constants 


A constant is a data item whose value cannot change. You refer to an arithmetic 
constant by directly representing the value of the constant, for example, 3.14. 
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Identifiers 


An identifier consists of one or more alphabetic characters, and may contain digits, 
break characters _ and the $, #, and @ characters. An identifier must start with an 
alphabetic character and must not exceed 31 characters. The break character 
improves readability, as in GROSS_PAY. 


If you use an identifier as a AS/400 program or file name, it must not exceed ten 
characters. 


An identifier can be a user-defined name or a PL/I keyword, depending on how it is 
used. 


User-Defined Names: A user-defined name, commonly called a name, is an identi- 
fier given to a variable or to a named constant. Any identifier can be used as a 
name. 


At any point in a program, a name can have only one meaning. For example, you 
cannot use the same name for both a built-in function and a variable in the same 
block. 


Examples of names are: 


A 
FILE2 
LOOP 3 
PAY_RATE 
#32 


Additional requirements for names are discussed later in this chapter. 


PL/I Keywords: A keyword is an identifier that has a specific meaning when used in 
the predefined context. A keyword can specify an action to be taken or the attri- 
butes of data. Some examples are the keywords READ, ENDFILE, and 
DECIMAL. Some keywords can be abbreviated; the abbreviation is shown in the 
description of the individual keywords. 


Delimiters 


Delimiters are used to separate identifiers and constants. Delimiters, other than 
operators, are shown in Figure 4-1; operators are shown in Figure 4-2. 


a 
blank = | Separates elements of a statement 


Figure 4-1 (Part 1 of 2). Delimiters 
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le 
Connects elements of a qualified name 


assignment Indicates assignment of a value. You can also 
symbol use the character = as a comparison operator 


parentheses () Encloses a list, expression, or iteration factor; 
encloses information associated with various 
keywords 


directive %INCLUDE Directs the compiler 
% PAGE 
% PROCESS 
*PROCESS 
%SKIP 


Figure 4-1 (Part 2 of 2). Delimiters 3 


a 


i =~ 


Subtraction or prefix minus 
Comparison 


Multiplication 
Division 
Exponentiation 


Greater than 
Not greater than 
Greater than or equal to 
Equal to 

Not equal to 

Less than or equal to 
Less than 
Not less than 


Figure 4-2 (Part 1 of 2). Operators 
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[sing | (Concannon 


Figure 4-2 (Part 2 of 2). Operators 


The characters that can be used as delimiters can also be used in other contexts. 
For example, the period is a delimiter when used in structure qualification, such as 
A.B, but it 1s not considered a delimiter when used in a decimal constant, such as 
3.14. 


Blanks: You can surround each delimiter with blanks. One or more blanks must 
separate identifiers and constants that are not separated by another delimiter. In 
general, any number of blanks can appear wherever one blank is allowed. 


Blanks cannot occur within identifiers, arithmetic and bit constants, or composite 
symbols. They are valid as data characters in character constants. 


Other cases that require or permit blanks (for example, in GO TO or GOTO) are 
noted in the text where the feature of the language is discussed. 


Some examples are: 
TABLE(10) is equivalent to TABLE ( 10 _ ) 
FIRST,SECOND is equivalent to FIRST, SECOND 
ABx«BC is equivalent to AB «« BC 
ABxxBC is not equivalent to AB « « BC 
Comments: You can use comments wherever blanks are allowed as delimiters in a 


program. A comment is treated as a blank and can therefore be used in place of a 
required separating blank. Comments do not affect the running of a program. 


ol 
text 


The composite symbol /* indicates the beginning of a comment and the composite 
symbol +/ indicates its end. The text can contain any of the language or extralingual 
characters, except the +/ composite symbol, which would end it. 


An example of a comment in an assignment statement is: 
A= 1; /* INITIALIZE «/ 


The following example assigns a character constant to A; it does not contain a 
comment: 


A='"/* THIS IS A CONSTANT, 
NOT A COMMENT «/'; 
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Program Organization 


This section discusses how a PL/I program is organized and how control flows 
between blocks. 


Programs 
A PL/I program is a collection of one or more procedures, called external 
procedures, each of which can contain internal procedures or begin-blocks or both. 


Activating a Program 


A PL/I program becomes active when a calling program calls the initial procedure. 
This calling program may be a AS/400 Control Language (CL) program, or it could 
be a program written in another high level language. The initial procedure must be 
one of the external procedures of the program. In the following example: 


CONTRL: PROCEDURE OPTIONS (MAIN) ; 
DECLARE (PROC1,PROC2,PROC3) ENTRY EXTERNAL; 
CALL PROC1; 
CALL PROC2; 
CALL PROC3; 
END CONTRL; 


the initial procedure is CONTRL,; it calls external procedures PROC1, PROC2, and 
PROC3. 


For more information about starting a PL/I program, see “Running the Program” 
on page 2-22. 


Ending a Program 


A program ends when the initial procedure ends. If a program ends normally or 
abnormally, control returns to the calling program. 


Blocks 


A block is the smallest delimited sequence of statements to which scoping and 
storage allocation rules apply. 


There are two kinds of blocks: procedures and begin-blocks. The maximum 
number of blocks in any external procedure is equal to 255 minus the number of 
on-units in the procedure. 


You can limit the scope of a name to a particular block (internal) or it can be 
known in all the blocks in a program (external). Storage may be allocated for a 
name only while a block is active (automatic) or while the program is running 
(static). You can define these attributes by explicit or implicit declarations within a 
block. (See “Names” on page 4-12 for more information about the scope of names 
and “STORAGE CONTROL” on page 5-15 for more information about the allo- 
cation of storage.) 
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You may find it easier to write and test a program by dividing it into blocks, partic- 
ularly when a number of programmers are writing parts of the same program. 


Some storage and some extra run time is used each time a block is activated. 
However, a program using multiple small blocks requires less storage to run, 
because storage for automatic variables is allocated on entry to the block, and is 
released on exit from the block. 


Activating a Block 


When an external procedure is called for the first time, storage is allocated for the 
static variables of all the blocks contained by the external procedure. 
When an internal procedure or begin-block 1s activated: 


e Array dimensions and string lengths of adjustable automatic variables which are 
not known at compile time are evaluated. The dimensions and lengths are 
those of the parameters passed to the procedure when it is called. 


e Storage is allocated for automatic variables. 


Begin-blocks and procedures are activated in different ways: 


¢ Procedures other than the initial procedure are activated only when they are 
called by a procedure reference (see “Activating a Procedure” on page 4-10). 


¢ Begin-blocks are activated through sequential flow (see “Activating a Begin- 
Block” on page 4-11) or by an on-unit. 


Ending a Block 


A procedure or begin-block can end in a number of ways, depending on the type of 
block. (See “Ending a Procedure” on page 4-11 and “Ending a Begin-Block” on 
page 4-12 for more information.) 


When a block ends: 


« The on-unit environment that existed before the block was activated is reestab- 
lished. 


e Storage for all automatic variables allocated in the block is released. 


e Static storage is released, and open files are closed if the block is the initial pro- 
cedure of the program. 


For more information on closing files, refer to “CLOSE Statement” on 
page 11-8. 


Storage allocated for an automatic variable cannot be referred to after the block con- 
taining the declaration of the variable has ended. If such a reference is attempted 
(by means of a pointer variable to which the address of the automatic variable has 
been assigned, for example), the results are undefined. Similarly, the value of a label 
or internal entry constant cannot be referred to after the block containing its declara- 
tion has ended. If such a reference is attempted (by means of a label or entry vari- 
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able to which the value has been assigned, for example), the results are undefined. 
Consider the following program: 


MAINPROC: PROCEDURE OPTIONS (MAIN); 
DECLARE (ITEM1,ITEM2) FIXED DECIMAL (3); 
ITEM1 = 5; 
ITEM2 = 8; 
BLOCK1: BEGIN; 
DECLARE BLOCKITEM 
FIXED DECIMAL (3,0) AUTOMATIC; 
BLOCKITEM = ITEMI1; 
STMT1: ITEM1 = 0; 
END BLOCK1; 
INVALID1: ITEM2 = BLOCKITEM; 
INVALID2: GO TO STMT1; 
END MAINPROC; 


When this program is compiled, the variable BLOCKITEM within the statement 
labelled INVALID1 will be identified as being in error. The compiler will not rec- 
ognize the variable name BLOCKITEM, because BLOCKITEM is declared in 
BLOCK 1, and its scope does not include statement INVALID1. Similarly, the 
label STMT 1 in statement INVALID2 will be identified as being in error. 


If a GO TO statement transfers control out of a block, several blocks may be ended. 
If the label specified in the GO TO statement is contained in a block that did not 
directly activate the block being ended, all currently activated blocks in the acti- 
vation sequence are ended. This is shown in the following example: 


A: PROCEDURE; 
statement-al 
statement-a2 
B: BEGIN; 

statement-bl 
statement-b2 
CALL C; 
statement-b3 
END B; 
statement-a3 
statement-a4 
C: PROCEDURE; 
statement-cl 
statement-c2 
statement-c3 
D: BEGIN; 
statement-dl 
statement-d2 
GO TO LAB; 
statement-d3 
END D; 
statement-c4 
END C; 
statement-a5 
LAB: statement-a6 
Statement-a/ 
END A; 
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In this example, procedure A activates begin-block B, which activates procedure C, 
which activates begin-block D. In D, the statement GO TO LAB transfers control 
to statement-a6 in A. Because this statement is not contained in D, C, or B, all 
three blocks are ended; A remains active. Therefore, the transfer of control out of D 
ends intervening blocks B and C as well as block D. 


Internal and External Procedures 
A procedure is a sequence of statements that may be called for processing at one or 
more points in one or more programs within a run unit. The first statement is a 
PROCEDURE statement and the last is a corresponding END statement. (See 
“PROCEDURE Statement” on page 14-2 and “END Statement” on page 13-10.) 


A procedure can be a subroutine or a function (see “Defining a Procedure” on 
page 14-1). 


Any block can contain one or more blocks nested within it; that is, procedures and 
begin-blocks can contain other procedures and begin-blocks, which can contain 
others, and so on. A block must completely encompass any block contained within 
it. 


A procedure can be external or internal. An internal procedure is contained in 
another block. An external procedure is not contained in another block. 


Begin-blocks are always internal: they are always contained in another block. In the 
following example, 
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A: PROCEDURE; 
B: BEGIN; 


END B; 
C: PROCEDURE; 


D: BEGIN; 


E: PROCEDURE; 
END Es 
END D; 


END C; 


END A; 


procedure A is an external procedure because 1t is not contained in any other block. 


Block B is a begin-block that is contained in A; it contains no other blocks. Block 
C is an internal procedure; it contains begin-block D, which in turn contains 
internal procedure E. There are three levels of nesting relative to A: B and C are at 
a depth of one, D is at a depth of two, and E is at a depth of three. 


The maximum depth of block nesting is 50. 


Activating a Procedure 


Normal sequential program processing ignores a procedure. Control passes directly 
from the statement immediately before the procedure’s beginning to the statement 
immediately following the procedure’s end. 


A procedure is activated or called by an entry reference: 


¢ Following the keyword CALL in a CALL statement (see “CALL Statement” 
on page 14-7). 


e In a function reference (see “Function Reference” on page 14-4). 
The point at which the entry reference appears is called the point of calling, and the 


block in which it appears is called the calling block. A calling block remains active 
when control is transferred to the called block. 
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When a procedure is called, processing begins with the first statement that can be 
processed. Processing is synchronous; that is, the calling procedure stops running 
until control is returned to it. 


Communication between two procedures is by means of variables (‘‘arguments’’) 
passed from the calling procedure to the called procedure, by variables returned 
from the called procedure, and by names known within both procedures. Therefore, 
a procedure can operate upon different data when it is called at different times. 


Ending a Procedure 


A procedure ends when: 


¢ A RETURN statement is processed within the procedure. Control then returns 
to the calling point in the calling procedure. If the calling point is a CALL 
statement, processing in the calling procedure resumes with the statement fol- 
lowing the CALL. If the point of calling is a function reference, processing 
resumes with the statement containing the reference. 


¢ The END statement of the procedure is reached. This is equivalent to a 
RETURN statement. 


¢ A GO TO statement is processed and control is transferred out of the proce- 
dure. (The GO TO statement is discussed under ‘““GO TO Statement” on 
page 13-11.) 


¢ A STOP statement is processed. This also ends the run unit. 


¢ A condition is raised and the implicit action ends the procedure. This also ends 
the run unit. 


A begin-block is a sequence of statements delimited by a BEGIN statement and a 
corresponding END statement. 


A label is optional for a begin-block. 


Activating a Begin-Block 


Begin-blocks are activated through normal flow or by error-handling on-conditions. 
In general, they can appear wherever a single statement can appear. 


When a begin-block is activated, the encompassing block or blocks remain active. 


Control can be transferred to a labeled BEGIN statement by means of a GO TO 
statement. 
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Ending a Begin-Block 


A begin-block ends when: 


¢ Control reaches the END statement for the block. Control is then transferred 
to the statement following the END statement. (See “Running an On-Unit” on 
page 10-3 for a discussion of normal return from an on-unit.) 


¢ A STOP statement is processed. This also ends the run-unit. 
¢ A condition is raised and the implicit action ends the run-unit. 


¢ A GO TO statement is processed and control is transferred to a point outside of 
the block. 


¢ A RETURN statement is processed and control is transferred out of both the 
begin-block and its containing procedure. 


You refer to each variable, and each file, label, and entry constant in a PL/I program 
by a name. 


Each name and its attributes must be made known in the block in which it is used 
by either an explicit or a contextual declaration. 


A name need not have the same meaning throughout a program. A name declared 
within a block has a meaning only within that block. Outside the block, it is 
unknown unless the same name is also declared in the outer block. The name in 
the outer block refers to a different data item. You can specify local definitions and 
write a block (a procedure or a begin-block) without knowing all the names being 
used in other blocks. 


The part of the program to which a name applies is called the scope of that name. 
Each declaration of a name establishes a scope for it. 


To understand the rules for the scope of a name, you need to know the meaning of 
the terms “contained in” and “internal to.” 


Everything in a block, from the PROCEDURE or BEGIN statement through to 
the corresponding END statement, is contained in that block. However, the label of 
the BEGIN or PROCEDURE statement that heads the block is not contained in 
that block. Nested blocks are contained in the block in which they appear. 


Elements contained in a block, but not contained in any block nested within it, are 
internal to that block. Consider the following example: 


PROC1: PROCEDURE; 
STMT1: INTEGER] = SQRT(INTEGER2); 
PROC2: PROCEDURE; 
STMT2: INTEGER3 = INTEGER1; 
END PROC2; 
END PROC1; 
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STMT1 and STMT2 are both contained in PROC1. STMT2 is also contained in 
PROC2. STMT1 is internal to PROC1. STMT2 is internal to PROC2. 


The entry name of an internal procedure or the label of a BEGIN statement is 
internal to the containing block. The entry name of an external procedure is not 
internal to the external procedure. 


Explicit Declaration of a Name 


A name is explicitly declared if it appears: 


¢ Ina DECLARE statement. The DECLARE statement explicitly declares attri- 
butes of names. 


¢ In a parameter list. The appearance of the name in a parameter list constitutes 
an explicit declaration of the name as a parameter of the containing procedure. 
The attributes for this parameter must be in a DECLARE statement internal to 
the same procedure. 


e As the label prefix of a PROCEDURE statement. A labeled PROCEDURE 
statement constitutes a declaration, within the containing block, of the proce- 
dure name as an entry constant. 


¢ As the label prefix of a statement other than a PROCEDURE statement. The 
label prefix constitutes an explicit declaration of a label constant within the con- 
taining block. 


Note: An explicit declaration overrides a contextual declaration. 
The scope of an explicit declaration of a name 1s the block it 1s internal to. This 


includes all contained blocks. This does not include blocks that have another 
explicit declaration of the same name internal to them. 


The syntax and use of the DECLARE statement is described in 
Chapter 12, “Declaring Names and Attributes of Variables.” 


Contextual Declaration of a Name 


Only built-in function and built-in subroutine names can be declared contextually. 
To contextually declare a name as a built-in function name, it must appear as a ref- 
erence and be followed by a parenthesized argument list. To contextually declare a 
name as a built-in subroutine name, it must appear as a reference in a subroutine 
call. 


Contextual declaration of a built-in function or built-in subroutine name has the 
same effect as if the name was declared in the external procedure, even when the 
statement that causes the contextual declaration is internal to another block that is 
contained in the external procedure. Consequently, the scope of the contextual dec- 
laration is the entire external procedure, except for any blocks in which the name is 
explicitly declared. 
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Scopes of Names 


Multiple declarations are not valid. They occur when two or more declarations of 
the same name are internal to the same block. Multiple declarations are valid when 
at least one of the names is declared within a structure in such a way that structure 
qualification can be used to make references unique. 


Figure 4-3 is a sample procedure that illustrates the scopes of data declarations. 
The brackets to the left indicate the block structure; the brackets to the right show 
the scope of each declaration of a name. The scopes of the two declarations of Q 
are shown as Q and Q’. 


A: PROCEDURE; 
DECLARE (P,Q) FLOAT; 
B: PROCEDURE; 
DECLARE Q FIXED, 
(R,X) FLOAT; 


DECLARE S FIXED; 
END C; 


C: PROCEDURE; | 
END A; 


Figure 4-3. Scopes of Data Declarations 
P is declared in block A and known throughout A. 


Q is declared in block A and in block B. The scope of the first declaration of Q is 
all of A except B; the scope of the second declaration of Q (Q’) is block B only. 


SIN is referred to in block B. This results in a contextual declaration in the external 
procedure A. This declaration therefore applies to all of procedure A, including its 
contained procedures B and C. 


S is explicitly declared in procedure C and is known only within C. R and X are 
declared in block B and are known only within block B. 


Figure 4-4 on page 4-15 illustrates the scopes of entry constant and statement label 
declarations. The example shows two external procedures. 
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Li Li' L2 A B C D E 
A: PROCEDURE; 
DECLARE E ENTRY; 
Li: P = Q; 
B: PROCEDURE; 
L2: CALL C; 
C: PROCEDURE; 
Ele cko=¥% 
| CALL E; 
END C; 
GO TO L1; 
END B; 
D: PROCEDURE; 
END 0D; 
CALL B; 


Cc END A; 
%PROCESS; 

e PROCEDURE; ] 
END E; 


Figure 4-4. Scopes of Entry and Label Declarations 


E is explicitly declared in A as an external entry constant. The explicit declaration 
of E in block A applies throughout block A; its explicit declaration as the entry con- 
stant of block E applies throughout block E. The scope of the name E is all of 

S block A and all of block E. The scope of the name A is all of the block A only, 
and not block E. 


The label L1 appears on statements internal to A and to C. Two separate declara- 
tions are therefore established; the first applies to all of block A except block C, and 
the second applies to block C only. Therefore, when the GO TO statement in 
block B is processed, control is transferred to L1 in block A, and block B 1s ended. 


B and D are explicitly declared in block A and can be referred to from anywhere 
( within A. Because they are internal, however, they cannot be referred to in block E. 


C is explicitly declared in B and can be referred to from within B, but not from 
outside B. 


L2 1s declared in B and can be referred to in block B, including C, which 1s con- 
tained in B, but not from outside B. 


If a PL/I keyword and its abbreviation are both declared as user-defined names in a 
program, the scopes of the two declarations may be different. For example: 
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A: PROCEDURE; 
DECLARE DEC FIXED DECIMAL (6), 
DECIMAL FILE; 
B: BEGIN; 
DECLARE DEC BUILTIN, 
(Y,Z) FIXED DECIMAL (6); 
Y=DEC(Z,6); 
END B; 
CLOSE FILE (DECIMAL); 
END A; 


DEC is known as a fixed-point decimal data item in block A, and as a built-in func- 
tion in block B, where it is declared again. DECIMAL is known as a file 
throughout blocks A and B. 


Using the Scope Attributes 


You can use the INTERNAL and EXTERNAL attributes to specify the scope of a 
name. 


For a description of the syntax of the scope attributes, INTERNAL and 
EXTERNAL, see “Scope Attributes” on page 12-40. For a description of how PL/I 
handles INTERNAL and EXTERNAL files, see “Scoping of Open Files (File 
Sharing)” on page 7-11. 


INTERNAL specifies that the name is known only in the declaring block. The 
scope of the name is the same as the scope of its declaration. Any other explicit 
declaration of that name refers to a new object with a different, non-overlapping 
scope. 


A name with the EXTERNAL attribute can be declared in more than one external 
procedure. It is linked across external procedures. No external name can be 
declared more than once in the same external procedure. The scope of the name 
includes the scopes of all the declarations of that name (with the EXTERNAL attri- 
bute) within the run unit. 


External names cannot exceed ten characters 1n length. 


Different declarations of the same name with the EXTERNAL attribute must have 
identical attributes after any defaults have been applied. 


When you declare a major structure name as EXTERNAL in more than one 
external procedure, the attributes of the structure members must be the same, 
although the corresponding member names need not be identical. For example: 
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PROCA: PROCEDURE; 
DECLARE 1 A EXTERNAL, 
2 B FIXED, 
2 C FLOAT; 


END PROCA; 


PROCB: PROCEDURE; 
DECLARE 1 A EXTERNAL, 
2 B FIXED, 
2 D FLOAT; 


END PROCB; 


In this example, if A.B is changed in PROCA, it is also changed in PROCB, and if 
it is changed in PROCB, it is also changed in PROCA. If A.C is changed in 
PROCA, A.D is changed in PROCB, and if A.D is changed in PROCB, A.C 1s 
changed in PROCA. 


The attribute listing, which is available as optional output from the compiler, helps 
to check the use and attributes of names. The following program example illustrates 
the use and attributes of names, and the rules for scopes of names: 


A: PROCEDURE; 
DECLARE S CHARACTER (21), 
M FIXED DECIMAL (7), 
N BINARY (15); 
DECLARE SYSIN FILE INPUT; 
DECLARE SET ENTRY(FIXED DECIMAL(1)); 
CALL SET (3); 
E: GET FILE(SYSIN) EDIT (S,M,N) 
(A(21) ,F (7) ,F(3))5 
B: BEGIN; 
DECLARE X(M,N) FIXED DECIMAL (7), 
Y(M) FIXED DECIMAL (7); 
GET FILE(SYSIN) EDIT (X,Y) 


(F(7),F(7))3 
CALL C(X,Y); 


C: PROCEDURE (P,Q); 
DECLARE (I,J) | FIXED BINARY (15) 
INTERNAL, 
P(*,*) | FIXED DECIMAL (7), 
Q (+) FIXED DECIMAL (7), 
FIXED BINARY (15) 


EXTERNAL, 
OUT ENTRY (LABEL) , 
SUM FIXED DECIMAL (9); 
S = 0; 
DO I =1 10M; 
SUM = 0; 
DO J=17T0N; 
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SUM = SUM + P(I,J); 
END; 
IF SUM = Q(I) THEN 
GO TO B; 
S$=S$ +1; 
IF § = 3 THEN 
CALL OUT (E); 
CALL D(I); 
B: END; 
END C; 
D: PROCEDURE (N); 
DECLARE N FIXED BINARY (15); 


DECLARE SYSPRINT FILE OUTPUT; 
PUT FILE(SYSPRINT) EDIT 
(‘ERROR IN ROW' , 
N, 'TABLE NAME ', S) 
(A(12) ,F (4) ,X(2), 
A(11),A(21))5 
END D; 
END B; 
GO TO E; 
END A; 
%PROCESS; 
OUT: PROCEDURE (R); 
DECLARE R LABEL, 
(M,L) FIXED DECIMAL (7) 
STATIC INTERNAL 
INITIAL (8), 
Ss FIXED BINARY (15) 
EXTERNAL; 
M+15 
0; 


M 
S 
IF M<L THEN STOP; 

ELSE GO TO R; 

END OUT; 
%PROCESS; 
SET: PROCEDURE(Z); 

DECLARE Z FIXED DECIMAL(1), 

L FIXED DECIMAL(1) STATIC 

L=Z; 

RETURN; 

END SET; 


A is an external name. The scope of A is all of block A, plus any other blocks 
where A is declared as external. 


S is declared in block A and block C, as well as in block OUT. The declarations of 
S in block C and in block OUT declare S as external. They specify identical attri- 
butes for S, and declare the same external variable. The declaration of S in block A 
introduces a different, internal variable. 


Within external procedure A, the character variable declaration of § applies to all of 
block A except block C. The fixed binary declaration of S applies only within block 
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C. Although D is called from within block C, the reference to S in the PUT state- 
ment in D is to the character variable S and not to the S declared in block C. 


N is a parameter in block D, but is also declared in block A. These two declara- 
tions on the name N refer to different objects, although, in this case, the objects 
have the same attributes, which are BINARY FIXED(15) and INTERNAL. 


X and Y are known throughout B and could be referred to in block C or D within 
B, but not in that part of A outside B. 


P and Q are parameters and therefore require explicit declaration. Although the 
arguments X and Y are declared as arrays and are known in block C, it is still neces- 
sary to declare P and Q in a DECLARE statement to establish that they, too, are 
arrays. (Asterisks indicate that the bounds of the parameters are taken from the 
corresponding arguments.) 


I and J are known only in block C. M is known throughout block A, including all 
its contained blocks. 


The second external procedure in the example has the entry name OUT, and the 
third external procedure has the name SET. The entry constants SET and OUT get 
the attributes ENTRY and EXTERNAL and are known throughout their external 
procedures. Because these external procedures are referenced in the external proce- 
dure A, they must be declared with an appropriate ENTRY attribute in procedure 
A. 


The label prefix B appears twice in the program. It is first declared explicitly by its 
appearance as the label of a begin-block A. It is declared again as a label within 
block C by its appearance as a prefix to an END statement. The GO TO B state- 
ment within block C, therefore, refers to the label on the END statement within 
block C. Outside block C, any reference to B would be to the label of the begin- 
block. 


C and D can be called from any point within B, but not from that part of A outside 
B or from another external procedure like OUT or SET. Similarly, because E is 
known throughout the external procedure A, a transfer can be made to E from any 
point within A. The label B within block C, however can only be referred to from 
within C. 


Control can be transferred out of a block and back to a block that was activated, by 
means of a GO TO statement. In the external procedure OUT, the label E from 
block A is passed as an argument to the label parameter R. The statement GO TO 
R causes control to pass to the label E, although E is declared within A and 1s not 
within OUT. 


The variables M and L are declared as STATIC within the procedure OUT; their 
values are preserved between calls to OUT. 
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Chapter 5. PL/I Data Organization and Use 


This chapter contains information on how data is stored and manipulated. Data 
items come in two forms: scalars, or aggregates. You can use alignment and 
mapping attributes as well as the DECLARE statement to control how this data is 
stored. There are three data types: arithmetic, character, and bit. You can assign 
data items to one of these types and convert between types using built-in conversion 
functions. 


DATA ORGANIZATION 


Data items can be single data items, called scalars, or they can be grouped together 
to form data aggregates, in which they can be referred to either individually or col- 
lectively. Data aggregates can be arrays or structures. A variable that represents a 
single data item is a scalar variable. A variable that represents an aggregate of data 
items is either an array variable or a structure variable. 


Any type of problem data variable or program control variable can be grouped into 
arrays or structures. 


Using Arrays and the Dimension Attribute 
An array is a collection, into one or more dimensions, of one or more array- 
elements with identical attributes. An array-element can be a scalar variable or a 
structure. Only the array itself is given a name. An individual item of an array is 
referred to by the array name and a subscript giving the item’s position inside the 
array. 


An array is declared with the dimension attribute, which defines the subscript 
format. For a description of the syntax of the dimension attribute, see “Arrays and 
the Dimension Attribute” on page 12-38. 


Examples of Array Declarations 
DECLARE LIST(8) FIXED DECIMAL (3); 


In the example above, LIST is declared a one-dimensional array of eight elements, 
each of which is a fixed-point decimal element of three digits. The single dimension 
of LIST has bounds of 1 and 8; its extent is 8. 


DECLARE TABLE1(4,2) FIXED DECIMAL (3); 


TABLE] is declared a two-dimensional array, also of eight fixed-point decimal ele- 
ments. The two dimensions of TABLE] have bounds of 1 and 4, and 1 and 2; the 
extents are 4 and 2. 


DECLARE TABLE2(10,1:8) FIXED DECIMAL (6,2); 


TABLE2 is declared a two-dimensional array of eighty fixed-point decimal elements, 
each with six digits, of which two are to the right of the decimal point. The two 
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dimensions of TABLE2 have bounds of 1 and 10, and 1 and 8; the extents are 10 J 
and 8. 


In AS/400 PL/I, the only lower bound you can specify is 1. 


DECLARE INDEX1 FIXED BINARY (15) STATIC INITIAL (8); 
DECLARE LIST(1:INDEX1) FIXED DECIMAL (4); 


The bounds of LIST are 1 and INDEX1, with INDEX1 initialized as 8. 


The following example shows a factored array declaration: 
DECLARE (A,B,C,D)(10) BINARY FIXED; 


The variables A, B, C, and D are to represent one-dimensional arrays, each con- 
sisting of ten fixed-point binary items with a default length of 15. 


Subscripts 


The dimensions of an array determine the way the elements of the array are referred 
to. For example, the array LIST, which is declared above as a one-dimensional 
array, can be considered as a linear sequence of eight elements. If the contents of 
the elements of the array are 


20 5 10 30 630 150 310 70 


in that order, they can be referred to as follows: J 
Reference Element 

LIST (1) 20 

LIST (2) 5 

LIST(3) 10 

LIST (4) 30 

LIST (5) 630 

LIST (6) 150 

LIST (7) 310 : 

LIST (8) 70 3 


Each of the numbers following LIST is a subscript. A subscript identifies a partic- 
ular element of the array. A reference to a subscripted name, such as LIST(4), 
refers to a single item. In the example, LIST(4) has a value of 30. The entire array 
can be referred to by the name of the array, with no following subscript. For 
example, all of the elements of LIST could be set to zero by the statement 

LIST = 0. 


The same data could be organized in the two-dimensional array TABLEI declared 


above. TABLE1 could then be considered as a matrix of four rows (m) and two 
columns (n), as follows: 
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TABLE] is referred to by a subscripted name with two parenthesized subscripts, 
separated by acomma. For example, TABLE1 (2,1) specifies the first item in the 
second row, which is 10. 


The use here of a matrix to illustrate TABLE] bears no relationship to the way in 
which the items are actually organized in storage. Elements of an array are stored in 
row major order with the right-most subscript varying most rapidly. For example, 
the array TABLE] is stored in the order TABLE1(1,1), TABLE1(1,2), 
TABLE1(2,1), TABLE1(2,2) and so on. 


A subscripted reference to an array must contain as many subscripts as there are 
dimensions in the array. (See ‘Arrays of Structures” on page 5-5 for arrays with 
inherited dimensions.) 


The examples in this chapter have arrays of arithmetic data. Variables of any data 
type except FILE can be collected into an array. String arrays (character or bit) are 
valid, as are arrays of label, entry, or pointer data. 


Expressions as Subscripts 


Any integer expression can be used as a subscript. The expression is converted to 
fixed-point binary with a precision of 31. Therefore, TABLE(I,J«K) could refer to 
the different elements of TABLE by varying the values of the integers I, J, and K. 


Using Structures and Level Numbers 
A structure is a collection of data items that need not have identical attributes. 


Like an array, the entire structure 1s given a name, which can be used to refer to the 
entire aggregate of data. But, unlike an array, each field of a structure also has a 
name. 


A structure has different levels. At the first level is the major structure; at lower 
levels are the minor structures; and at the lowest are the fields of the structure. A 


structure field can be a scalar variable or an array. 


The members at the next lower level of a structure or substructure are the immediate 
components of the structure or substructure. 
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You specify the organization of a structure in a DECLARE statement by placing 
level numbers before the names, as described in “Structures and Level Numbers” on 
page 12-39. The major structure name must be declared with the level number 1, 
and minor structures and field names with level numbers greater than 1; level 
numbers must be integer constants. 


For example, the items of a payroll could be declared as follows: 


DECLARE 1 PAYROLL, 
2 EMPLOYEE_NO FIXED DECIMAL (7), 


2 NAME, 
3 LAST CHARACTER (15), 
3 FIRST CHARACTER (15), 
2 HOURS, 


3 REGULAR FIXED DECIMAL (5,2), 

3 OVERTIME FIXED DECIMAL (5,2), 
2 RATE, 

3 REGULAR FIXED DECIMAL (5,2), 

3 OVERTIME FIXED DECIMAL (5,2); 


In this example, PAYROLL is a major structure with the immediate components 
EMPLOYEE NO, NAME, HOURS, and RATE. EMPLOYEE NO is a field; 
NAME, HOURS, and RATE are minor structures, each containing two fields. 
You can refer to the entire structure by the name PAYROLL, to portions of the 
structure by the minor structure names, or to a field by the name of the field. 


The level numbers you choose for successively deeper levels need not be the imme- 
diately succeeding integers. A minor structure at level m contains all the names with 
level numbers greater than n that lie between that minor structure name and the 
next name with a level number less than or equal to 7. 


PAYROLL could have been declared as follows: 


DECLARE 1 PAYROLL, 
4 EMPLOYEE_NO FIXED DECIMAL (7), 


3 NAME, 
5 LAST CHARACTER (15), 
5 FIRST CHARACTER (15), 
2 HOURS, 


6 REGULAR FIXED DECIMAL (5,2), 

5 OVERTIME FIXED DECIMAL (5,2), 
2 RATE, 

45 REGULAR FIXED DECIMAL (5,2), 

30 OVERTIME FIXED DECIMAL (5,2); 


This declaration would result in exactly the same structuring as that of the previous 
declaration. 


Therefore, there is a difference between logical level and level number. The item 
with the greatest level number is not necessarily the item with the deepest logical 
level. But if the structure declaration is written with consistent level numbers and 
suitable indentation, the logical levels are immediately apparent. 
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You can, in any case, determine the logical level of each item in the structure by 
applying the following rule to each item in turn, starting at the beginning of the 
structure declaration: the logical level of a given item is always one unit deeper than 
that of its immediate containing structure. For example, in the first declaration of 
PAYROLL, the logical levels and level numbers are the same. In the second decla- 
ration, the level numbers are different, but the logical levels are the same as in the 
first declaration. 


The description of a major structure is ended by the declaration of another item 
with the level number 1, by the declaration of another item with no level number, 
or by the end of the DECLARE statement or descriptor list. 


The maximum depth of logical levels is 15, and the highest valid level number is 
255. The maximum length of a structure is 32 767 bytes. 


Structure-Qualification 


A minor structure can be referred to by the minor structure name alone and a struc- 
ture field by the field name alone if there is no ambiguity. In the PAYROLL 
example, a reference to either REGULAR or OVERTIME would be ambiguous 
without structure-qualification to make the reference unique. 


A qualified reference is a field name or a minor structure name that is qualified with 
one orf more names at a higher level, connected by periods. Blanks may appear on 
either side of the period. 


Structure-qualification is in the order of levels; that is, the name at the highest level 
must appear first, with the name at the deepest level appearing last. 


Names within a structure need not be unique within the block in which they are 
declared. Also, one or more qualifying names can be omitted, provided that the 
name or names used identify a single field or minor structure. The qualified refer- 
ences PAYROLL.LAST and NAME.LAST, for example, are both equivalent to 
the name PAYROLL.NAME.LAST. 


Arrays of Structures 
A structure name, either major or minor, can be given a dimension attribute in a 
DECLARE statement to declare an array of structures. An array of structures is an 
array whose elements are structures that have identical names, levels, and element 
attributes. 


For example, if you were to use a structure, WEATHER, to process meteorological 
information for each month of a year, you might declare it as: 
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DECLARE 1 WEATHER(12), 
5 TEMPERATURE, 


10 HIGH DECIMAL FIXED (5,1), 
10 LOW DECIMAL FIXED (3,1), 
5 WIND VELOCITY, 
10 HIGH DECIMAL FIXED (3), 
10 LOW DECIMAL FIXED (3), 
5 PRECIPITATION, 
10 TOTAL DECIMAL FIXED (3,1), 
10 AVERAGE DECIMAL FIXED (3,1); 


You could then refer to all the weather data for July by specifying WEATHER(7) 
and to the particular aspects of the July weather by TEMPERATURE(7) and 
WIND _VELOCITY(7). The specifications PRECIPITATION.TOTAL(7) and 
TOTAL(7) would both refer to the total precipitation during the month of July. 


TEMPERATURE.HIGH(3), which would refer to the high temperature in March, 
is a subscripted qualified reference. 


The need for subscripted qualified references becomes more apparent when an array 
of structures contains an array of minor structures. For example, consider the fol- 
lowing array of structures: 


DECLARE 1A (6,6), 
5B (5), 

10 C FIXED, 

10 D FIXED, 
E FIXED; 


Both A and B are arrays of structures. To reference a data item, it may be neces- 
sary to use as many as three names and three subscripts. 


You must include the subscripts to the right of the name or qualified list of names. 
For example, A.B.C(1,1,2) is valid, whereas A(1,1).B(2).C is not. A.B.C(1,1,2) ref- 
erences a particular C that is in an element of B in a structure in A. 


Any item declared within an array of structures inherits dimensions declared in the 
containing structure. For example, in the above declaration for the array of struc- 
tures A, B is a three-dimensional array of structures, because it inherits the two 
dimensions declared for A. If B is unique and requires no qualification, any refer- 
ence to a particular element of B would require three subscripts: two to identify the 
specific structure in A and one to identify the specific element of B within that 
structure in A. 


A reference to an array with inherited dimensions must be subscripted, and the 
number of subscripts must equal the number of inherited dimensions or the total 
number of dimensions of the array. Therefore, with the declaration above, A, 
A(1,2), B(,2), B(1,2,3) and C(1,2,3) are valid references, but B, C, and C(1,2) are 
not. 
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Performance Considerations with Large Aggregates 


Programs which process large STATIC or AUTOMATIC aggregates (those 
approaching or exceeding 32 767 bytes in size) may take a long time to run. The 
reason for this is that the machine brings into main memory all static and automatic 
work areas before running the program. If the work areas become too large, the 
excessive paging results in system overhead which can significantly increase the time 
required to run the program. 


You can reduce this paging activity by declaring large aggregates as BASED vari- 
ables and using the ALLOCATE statement (see “ALLOCATE Statement for Based 
Variables” on page 5-22) before referencing the variables. Allocated storage for 
BASED variables is paged into main memory on a demand “paging” basis: only the 
pages that the program references are paged in. 


Data Alignment and the Alignment Attributes 


Data is stored in units of eight bits, or a multiple of eight bits. Each eight-bit unit 
of information is called a byte. 


Bytes may be grouped together in units of information as a halfword (two bytes), a 
word (four bytes; also called a fullword), a doubleword (eight bytes), ora 
quadword (16 bytes), starting at an integral boundary for that unit. An integral 
boundary for a unit is at a multiple of that unit: a byte boundary can be at any byte, 
a halfword boundary at a multiple of two bytes, a word boundary at a multiple of 
four bytes, a doubleword at a multiple of eight bytes, and a quadword at a multiple 
of 16 bytes. 


Byte locations in storage are consecutively numbered, starting with zero. Each 
number is considered the address of the corresponding byte. A group of bytes in 
storage is addressed by the leftmost byte of the group. 


A field aligned on a halfword or word boundary can be accessed faster than a field 
of the same length that is not aligned on an integral boundary. For some oper- 
ations, the data used must be aligned on its integral boundary. 


Data items can be aligned on their integral boundaries to give the fastest possible 
processing. But this is not always desirable, as there may be unused bytes between 
successive data items, which increases the use of storage. This is particularly impor- 
tant when the data items are members of aggregates that are used to create a file, 
because the unused bytes will increase the amount of external storage required. 
Consequently, although the UNALIGNED attribute may increase run time, it can 
reduce storage requirements. 


By means of the ALIGNED and UNALIGNED attributes, you can choose to align 
data on the appropriate integral boundary. 


ALIGNED specifies that the data item is aligned on the storage boundary corre- 
sponding to its data type requirement. For example, BIN (15) data is aligned on a 
halfword boundary and BIN (31) data on a fullword boundary. See “Data 
Mapping” on page 5-9 for a definition of these requirements. 
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UNALIGNED specifies that the data need not be aligned. The compiler may gen- JS 
erate code that moves the data to an appropriate integral boundary before an opera- 
tion is processed, if the operation requires data alignment. 


Bit data must be declared as ALIGNED. Aligned bit strings start at a byte 
boundary. Consider the following example: 


DECLARE BITSTRING] BIT (3) ALIGNED, 
BITSTRING2 BIT (5) ALIGNED; 


BITSTRINGI starts on a byte boundary. BITSTRING2 starts on the next byte 
boundary. The five bits intervening between BITSTRINGI and BITSTRING2 are 
not addressable by the program. 


The default for character data and picture data is UNALIGNED. For all other data 

types, the default is ALIGNED. If you specify UNALIGNED with character data, 

the compiler will issue an error message. If you specify ALIGNED with non- J 
varying character data, the specification of ALIGNED will be ignored, and the com- 

piler will issue an error message. 


You can specify alignment attributes for scalars and arrays only. 


ALIGNED can be specified for character varying data and must be specified for bit 
data. 


UNALIGNED can be specified for fixed-point binary, floating-point binary, and , 
floating-point decimal data. S) 


The following example illustrates explicit and default alignment. 
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DECLARE 1 SAMPLESTRUCTURE, 
5 BIT] BIT (3) ALIGNED, 
/» ALIGNED EXPLICITLY  «/ 


5 MINORSTRUCTURE1, 
10 BIT2 BIT (5) ALIGNED, 
/« ALIGNED EXPLICITLY  #/ 


10 MINORSTRUCTURE2, 
15 BINFLT1 FLOAT UNALIGNED, 
/« UNALIGNED EXPLICITLY «/ 


15 DECFIXED FIXED DECIMAL, 
/» ALIGNED BY DEFAULT «/ 


15 CHARI CHARACTER (1), 
/» UNALIGNED BY DEFAULT «/ 


15 CHAR2 CHARACTER(2) 
VARYING ALIGNED, 
/» ALIGNED EXPLICITLY +«/ 


10 BINFIXED1 FIXED, 
/» ALIGNED BY DEFAULT «/ 


5 PIC] PICTURE '99.V9'; 
/» UNALIGNED BY DEFAULT «/ 


This section describes the mapping of data onto storage. In general, you need not 
know the precise rules for data mapping; the compiler can print an aggregate length 
table of all the arrays and major structures in the source program. (You can print 
this table using the «AGGREGATE option of the OPTION parameter for the CL 
command CRTPLIPGM. See Chapter 2, “Creating, Compiling, and Running 
Your PL/I Program” for more information.) However, you may want to know the 
rules for data mapping in the following cases: 


e To determine record lengths and alignments when you use record data trans- 
mission. 


¢ To determine the correspondence of pointers and based variables. 

e When using the UNSPEC built-in function or pseudovariable. 
A unit of data is mapped onto storage by determining the alignment (a), displace- 
ment (d), and length (I) of the unit, where: 
a _is the alignment boundary: 


a=1 for byte alignment 

a=2 for halfword alignment 
a=4 for word alignment 

a=8 for doubleword alignment. 
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a= 16 for quadword alignment. 


d is the displacement, in bytes, of the start of the unit from the alignment 
boundary. 


| is the length, in bytes, of the unit. 


Scalar Data Mapping 
The scalar data mapping algorithm derives immediately from Figure 5-1. The 
values of “a” and “1” are determined from the appropriate variable type in the 
figure. The value of “d” is always 0. 


Examples: 


DECLARE A BINARY FIXED (15) ALIGNED 
where: a=2, d=0, 1=2 

DECLARE B BINARY FIXED (12) ALIGNED 
where: a=2, d=0, l=2 

DECLARE C BINARY FIXED (31) UNALIGNED 
where: a=1, d=0, 1=4 

DECLARE A BIT (2) ALIGNED 
where: a=1, d=0, 1=1 


Variable 
Type 


Stored 
internally 
as 


One byte for 
each group 
BIT (n) of 8 bits ceil(n/8) Byte Not 
(or part applicable 
thereof) 


CHARACTER One byte per Not Byte 
(n) character applicable 


PICTURE One byte for Number of 
each PICTURE | PICTURE Not Byte 
character characters applicable 
(except V) (other than V) 


Packed 
decimal 
format (1/2 
byte per 
digit, plus 
1/2 byte for 
sign) 


CHARACTER (n)| One byte per n+2 
VARYING character 


Figure 5-1 (Part 1 of 2). Storage and Alignment Requirements of Scalar Data 


Length ALIGNED UNALIGNED 
(in bytes) boundary boundary 


DECIMAL 
FIXED 


(p,q) 


ceil((p+1)/2) Not 


applicable 


Halfword 
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BINARY 
FIXED (p) 
lsps 15 


BINARY 
FIXED (p) 
l6< ps 3l 


BINARY 
FLOAT (p) 
l<ps 24 


DECIMAL 
FLOAT (p) 
l<ps<7 
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Stored Length ALIGNED UNALIGNED 

internally (in bytes) boundary boundary 

as | 

Halfword 

binary integer 2 Halfword?! 

Fullword 

binary integer Word! 
ee 


POINTER 16 Quadword Not appli- 
cable 


BINARY 
FLOAT (p) 
2<ps 353 


DECIMAL 
FLOAT (p) 
8<sps 16 


Doubleword 
within struc- 
tures; other- 
wise word! 


Doubleword 
within struc- 
tures; other- 
wise word! 


Figure 5-1 (Part 2 of 2). Storage and Alignment Requirements of Scalar Data 


Array Mapping 


Footnotes 
1 This is the default alignment boundary. 


Note: For a table of ceil values, see Figure 9-4 on page 9-9. 


The alignment (a'), displacement (d'), and length (1') of an array element can be 
calculated using the rules given in the preceding section for an array of scalars, or in 
the following section for an array of structures. In the following equations, N is the 
number of array elements. 
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The padding required between an array element ending at d'+1' and the next 
element starting at d' is 


pad = mod(-1',a') 


where mod gives the smallest non-negative remainder after division. 


No padding is needed after the last element. The total length of the array is there- 
fore 


1 = Nel' + (N-1) » pad 
The alignment boundary and displacement of the array are those of the element: 


a =a' 
d=d' 


For example: 


DECLARE 1 A (2,5), 
5 B BINARY (15), 
5 C BINARY (31); 


A 1s an array of structures. According to the rules for mapping a structure, which 
are given in the next section, each element of A has a length of 6 bytes and starts at 
a displacement of 2 bytes from a word boundary: 


a'=4, d'=2, 1'=6 

The number of array elements (N) is ten. The padding between successive elements 
iS: 

pad = mod(-6,4) = 2 

The array is therefore mapped as: 


a=4 
d=2 
] 10x6 + 9x2 = 78 


Structure Mapping 


The rules for structure mapping are: 
1. Map the first immediate component, resulting in a, d, and 1. 


2. Given that the structure consisting of the first k immediate components has 
been mapped into a, d, and 1 (initially k= 1, and a, d, and 1 are the values 
obtained from step 1), map the immediate component k+1, to obtain a', d' 
and 1'. Combine the two units therefore obtained according to the rules given 
below, to obtain a, d, and | for the structure consisting of the first k+1 compo- 
nents. 


3. Repeat step 2 with increasing values of k until the whole structure has been 
mapped. 


This process is recursive if any of the components of the structure you are mapping 
is a structure. 
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To combine a unit mapped as al, dl, and 11 and a unit mapped as a2, d2, and 12 
into a new unit, which is mapped as a, d, and 1, proceed as follows: 


1. Some padding may be required after the first unit, which ends at d1+11, to align 
the second unit at d2: 


pad = mod(d2-(d1+11), min(al,a2)) 


(This is calculated relative to min(al,a2), which is the weaker of the two align- 
ment boundaries. The proper boundary is taken into account in the calculation 
of a and d below.) Again, mod gives the smallest non-negative remainder after 
division. The offset of the second unit from the start of the new unit will be 


11 + pad 

2. The length of the new unit will be 
1 = 11 + pad + 12 

3. Compare the alignment boundaries of the two units. If a2 > al (that is, if the 
alignment of the second unit is stronger than that of the first), the alignment 


boundary of the new unit is that of the second, and the displacement of the new 
unit must be calculated from that boundary: 


ad 
mod(d2-(11+pad), a2) 


a 
d 


If a2 < al, the alignment boundary and displacement of the new unit are those 
of the first unit: 


Example of Structure Mapping 


This example shows the application of the structure mapping rules for a structure 
declared as follows: 


DECLARE 1 A, 


5 B, 
10 C CHARACTER (2), 
10 D FLOAT DECIMAL (8), 
10 E BIT (2) ALIGNED, 
10 F CHARACTER (4), 

5 G, 
10 H BINARY (4), 


H 
10 I PICTURE 'V99', 
J CHARACTER (1), 
10 K FLOAT DECIMAL (1); 


Figure 5-2 and Figure 5-3 on page 5-14 show the steps involved in mapping the 
minor structures B and G, respectively. Figure 5-4 on page 5-15 shows how the 
results of mapping the two substructures B and G are combined to map the major 
structure A. The storage layout of structure A is shown in Figure 5-5 on 

page 5-15. 
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id EE 
F ] 4 1] 
Boots jo fw ff] 


Figure 5-2. Mapping Minor Structure B 


As an example of applying the rules for combining two units, consider the step of 
combining units C and D in Figure 5-2. C and D have been mapped as 


al=1, dl=06, 11=2 
and 
a2=8, d2=0, 12=8 


respectively (these values are obtained from Figure 5-1 on page 5-10). No padding 
is required: 


pad = mod(d2-(d1+11),al) = mod(@-2,1) = 0 
D has the stronger boundary (a2 = 8), so 
a=a2=8 
and 

= mod(d2-(11+pad),a2) = mod(0-2,8) = 6 
and 
1] = 11+ pad + 12=2+0+ 8 = 10 


The unit obtained, which consists of fields C and D, will be used as the first unit in 
the next step. 


Figure 5-3. Mapping Minor Structure G 


As a second example, consider the step of combining the unit consisting of the fields 
H, I, and J with unit K, as shown in Figure 5-3, where 
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and 
a2=4, d2=0, 12=4 
The padding between the two units is 
pad = mod(d2-(d1+11),a1) = mod(0-5,2) = 1 
Again, the second unit has the stronger boundary (a2 = 4), so 
=a2 = 4 
and 
d = mod (d2-(11+pad) ,a2) = mod(0-6,4) = 2 
and 
=ll+pad+12=5+1+4+4=10 


The resulting unit, G, is used as the second unit in Figure 5-4. 


a ae ee aM 


15 
z : 10 16 


Foes ae A 


Figure 35-4. Mapping Major Structure A 


Figure 5-5 shows the resulting storage layout of structure A. 


Alignment Padding Offset Displacement 
Requirement after from A from 
Item (in bytes) Doubleword 
byte 


doubleword 


byte 
byte 
halfword 
byte 
byte 


word 


Figure 5-5. Storage Layout of Structure A 
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The following describes how to control the allocation of storage. 
Variables of both problem data and program control data require storage. The attri- 


butes specified for a variable define the amount of storage required and how it 1s 
interpreted. For example: 
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DECLARE INTEGER] FIXED BINARY (31) AUTOMATIC; 


A reference to INTEGER] is a reference to a fullword that contains a value to be 
interpreted as a fixed-point binary integer (see “Data Mapping” on page 5-9). 


Storage allocation is the association of an area of storage with a variable, so that the 
data item to be represented by the variable can be recorded internally. When 
storage has been associated with a variable, the variable is said to be allocated. 


The declaration of a variable includes a storage class attribute either by explicit spec- 
ification or by default. 


The way storage is allocated for a variable, and the degree of control you can exer- 
cise over storage, are determined by the storage class of that variable. There are 
three storage classes: static, automatic, and based. Each is specified by its corre- 
sponding storage class attribute. 


You can specify the storage class for level-one variables only. Elements of arrays 
and members of structures inherit the storage class of the array or structure. 


You cannot specify a storage class for a parameter or a named constant. 


The default storage class attribute is AUTOMATIC for internal variables and 
STATIC for external variables. 


Automatic and based variables can have internal scope only. Static variables can 
have either internal or external scope. 


Using the STATIC Attribute 


The allocation of storage for a static variable depends on the scope of the variable: 


e If the variable has the INTERNAL attribute, storage is allocated on the first 
entry to the external procedure that contains the declaration. 


e If the variable has the EXTERNAL attribute, storage is allocated on the first 
entry to the first external procedure that contains the declaration. 


Storage for a static variable remains allocated until the run unit ends. 


When storage is allocated, it is not initialized with zeros or blanks; the program 
must explicitly assign any initial values either by assignment statements or by use of 
the INITIAL attribute. 


Variables declared with the STATIC attribute follow normal scope rules for the 
validity of references to them. For example: 
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MAINPROC: PROCEDURE OPTIONS (MAIN); 


SUBPROC: PROCEDURE; 
DECLARE INTEGER1 FIXED STATIC INTERNAL; 


END SUBPROC; 
END MAINPROC; 


In this example, although the variable INTEGER] is allocated throughout the 
program, it can be referenced by the name INTEGER only within SUBPROC or 
any block contained in SUBPROC. 


Using the INITIAL Attribute 
The INITIAL attribute can only be used with the STATIC attribute. It specifies 
values assigned to a scalar or array variable when storage is allocated to it. 


For a description of the syntax of the INITIAL attribute, see “INITIAL Attribute” 
on page 12-42. 


You can specify the INITIAL attribute for arrays that do not have inherited dimen- 
sions, as well as for scalar variables. In a structure declaration, you can specify the 
INITIAL attribute only for field names. 


You can specify only one initial value for a scalar variable, but more than one for 
an array variable. A structure variable requires separate initialization of each of its 
field names, if they are scalar or array variables. 


The initial values specified for an array are assigned to successive elements of the 
array in row-major order, with the final subscript varying most rapidly. 


If you specify fewer initial values than there are array elements, the remainder of the 
array is not initialized. 


In the INITIAL attribute, you can specify only character, bit, or arithmetic con- 
stants (such as '‘ABC', '101'B, or 3) or the NULL built-in function (to initialize a 
static pointer variable). 


For an array, the iteration factor specifies the number of times the item is to be 
repeated in the initialization of elements of the array. 


If the attributes of any item in the INITIAL attribute differ from the attributes of 
the variable being initialized, conversion is processed. 


The INITIAL attribute for a static external variable is ignored in all but the external 
procedure that allocated storage for the variable. 
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Consider the following examples: 


DECLARE NAME CHARACTER (10) STATIC 
INITIAL (‘JOHN DOE'); 


DECLARE PI FIXED DECIMAL (5,4) STATIC 
INITIAL (3.1416); 


When storage is allocated for NAME, it 1s initialized with the character string ' JOHN 
DOE' (padded on the right, with blanks, to 10 characters). When PI 1s allocated, it is 
initialized to the value 3.1416. The value can be retained throughout the program 
or changed while running. 


Other examples are: 


DECLARE SWITCH BIT (1) STATIC 
INITIAL ('1'B); 


DECLARE MAXVALUE FIXED DECIMAL (2) 
STATIC INITIAL (99), 

MINVALUE FIXED DECIMAL (2) 
STATIC INITIAL (-99); 


Consider the following example: 


DECLARE A(15) CHARACTER(13) STATIC INITIAL 
("JOHN DOE’, 
‘RICHARD ROW', 
‘MARY SMITH"), 
B(10,10) DECIMAL FIXED(5) STATIC 
INITIAL ( (25) 0, (25) 1, (50)0) ; 


In this example, only the first, second, and third elements of array A are initialized; 
the rest of the array is uninitialized. The array B is fully initialized, with the first 25 
elements initialized to 0, the next 25 to 1, and the last 50 to 0. 


Using the AUTOMATIC Attribute 
Storage for an automatic variable is allocated on entry to the block in which it has 
been declared and is released when the block ends. Therefore, it can be reallocated 
many times during the running of a program. For a description of the syntax of the 
AUTOMATIC attribute, see “AUTOMATIC Attribute” on page 12-41. 


You control the allocation of storage for an automatic variable by means of the 
block structure of your program. For example: 
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PROC1: PROCEDURE; 


CALL PROC2; 
PROC2: PROCEDURE; 
DECLARE (INTEGER1,INTEGER2) FIXED AUTOMATIC; 


END PROC2; 
CALL PROC2; 


END PROC1; 


In this example, each time PROC2 is called, the variables INTEGER] and 
INTEGER2 are allocated storage, and when PROC2 ends the storage is released. 
Consequently, the values they contained are lost. The storage that has been released 
is available for reallocation to other variables. 


You can specify an array bound or string length for an automatic variable as an 
integer constant or as an unsubscripted reference to an automatic, static, or param- 
eter integer variable. In the latter case, the amount of storage allocated is deter- 
mined while the program is running. For example: 


A: PROCEDURE; 
DECLARE N FIXED BINARY; 
GET EDIT(N) (F(5)); 


B: PROCEDURE; 
DECLARE STR CHARACTER(N) ; 


END B; 
END A; 


In this example, the character string STR will have a length defined by the value of 
the variable N that existed when procedure B was called. 


A string length or array bound for an automatic variable must not be specified by 
means of another automatic variable declared in the same block. 


Using the BASED Attribute 
Based variables provide attributes for data accessed by a pointer value, such as data 
located in a buffer. 


You declare a based variable with the BASED attribute. For a description of the 
syntax of the BASED attribute, see ‘‘BASED Attnbute” on page 12-42. 
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A based variable is always used together with a pointer value, which is taken from 
either the pointer-qualifier or the declaration of the based variable. This is described 
under “Based Variable Reference and Pointer Qualification” on page 5-20. 


An example of a declaration of a based variable is: 
DECLARE PLAYERS(30) CHARACTER (20) BASED (POINTER); 


In this example, PLAYERS is a 1-dimensional array of character data, with 30 ele- 
ments. It’s purpose is to redefine the characteristics of storage occupied by data 
assigned to another character variable, which might be declared as: 


DECLARE TEAMS(2,15) CHARACTER (20); 


After processing the assignment POINTER1 = ADDR(TEAMS), the reference 
PLAYERS or POINTER1— > PLAYERS refers to the same location in storage as 
the reference TEAMS, and PLAYERS(20) or POINTER1 — > PLAYERS(20) is 
equivalent to TEAMS(2,5). 


Based Variable Reference and Pointer Qualification 


The name of a based variable, by itself, refers only to a collection of attributes. If it 
is to refer to a variable in storage, it must be associated with a pointer value, either 
explicitly or implicitly. 


The syntax of a based variable reference is 


“Tk 
pointer_expression —> 


pointer_expression 
Is an expression of type pointer. 


based_variable_reference 
Is a reference to a based variable. 


The pointer expression followed by the arrow is a pointer qualifier. If it is present, 
the variable reference is a pointer-qualified reference, and the association of the 
based variable with a pointer expression is called pointer qualification. 


If no pointer qualifier is present, the based variable must have been declared with a 
pointer variable in the BASED attribute. The pointer variable is then implied as a 
pointer qualifier. 


For example: 


DECLARE INTEGER1  BINARY(15) BASED, 
INTEGER2 § BINARY(15) BASED (POINTER2) , 
POINTERL POINTER, 
POINTER2 POINTER; 


POINTER1->INTEGER1 = INTEGER2; 
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The reference to INTEGER is explicitly qualified by POINTER1. The reference 
to INTEGER2 is implicitly qualified by POINTER2. 


When a reference to a based variable is evaluated, the explicit or implicit pointer 
qualifier is evaluated first, which gives a pointer value. This value must not be the 
null pointer and must not identify a location that has been released. The location of 
data in storage is identified by that pointer value, and the attributes of the data by 
those of the based variable. 


Therefore, in the example above, POINTER1— > INTEGER refers to the data 
accessed by POINTER 1 and described by the attributes of INTEGER, and 
INTEGER2 refers to the data accessed by POINTER2 and described by the attri- 
butes of INTEGER2. 


Multiple Pointer Qualification 


In a pointer-qualified reference, the pointer qualifier can be a variable reference, and 
can again be pointer-qualified. This leads to multiple pointer qualification. For 
example: 


DECLARE P_ POINTER, 

Q POINTER BASED (P), 

R BINARY(15) BASED, 

QA POINTER, 

RA BINARY (15); 
P = ADDR(QA); /x P points to QA «/ 
P->Q = ADDR(RA); /«* QA points to RA «/ 
P->Q->R = 17; /* RA = 17 «/ 


In this example, P— > Q-— >R is a reference to the based variable R with a pointer 
qualifier P— >Q, which is a reference to the based pointer variable Q with a pointer 
qualifier P. After the assignment to P, the references P— > Q and Q are equivalent 
to QA. After the assignment to Q, the references P— > Q- >R and Q-— >R are 
equivalent to RA. By using implicit qualification, the assignments could be written 
as follows: 


= ADDR(QA); 
Q = ADDR(RA); 
Q->R = 17; 


Pointer qualifiers can be subscripted and can be references to functions that return 
pointers. For example, given the declarations 


DECLARE P(10) POINTER, 
Q ENTRY(CHARACTER()) RETURNS (POINTER) BASED, 
R BINARY (15) BASED; 


a valid reference (with suitable declarations for A and I) is 
P(I)->0(A)->R 
P(I) points to an entry value that accepts a character value as its argument and 


returns a pointer value. This entry is called with argument A. The returned pointer 
is used to access R. If Q is declared with no arguments: 


DECLARE Q ENTRY() RETURNS(POINTER) BASED; 
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the reference must have an empty argument list: 
P->Q()->R 


because Q refers to the entry value and not to the pointer returned by calling Q(). 


Relationship of Pointers and Based Variables 


The data type of a based variable and the variable pointed to must match. This is 
true for scalars, and the elements of arrays and structures. According to the data 
mapping algorithm given under “Data Mapping” on page 5-9, this will be the case 
if: 


¢ Both variables are scalar with identical data and alignment attributes, or the one 
is a character variable and the other a picture variable of equal length. 


¢ Both variables are arrays with matching element descriptions. The number of 
dimensions or elements need not be the same, but the element or elements actu- 
ally referred to must be contained in both descriptions. 


¢ Both variables are structures whose attributes are identical up to the part 
referred to, including any minor structure containing the part. 


In the examples of arrays given under ‘Using the BASED Attribute” on page 5-19, 
PLAYERS is used as a based variable and TEAMS as the variable pointed to. 


In the following example: 


DECLARE INTEGER1 FLOAT, 
CHARSCALAR CHARACTER (15), 
CHARARRAY(15) CHARACTER (1) BASED (P); 


a valid reference is: 
ADDR (CHARSCALAR) ->CHARARRAY 


An example of structures is given in “Based Variables and Input/Output” on 
page 5-23. 


ALLOCATE Statement for Based Variables 


The ALLOCATE statement allocates storage for based variables and sets a pointer 
variable that can be used to identify the location, independent of procedure block 
boundaries. 


The syntax of the ALLOCATE statement for based variables 1s: 


>»>——-ALLOCATE——based_variable—SET(pointer_variable) ;——>< 


Abbreviation: ALLOC for ALLOCATE 
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based_variable 
Can be any data type. It may be an element variable, an array, or a major 
structure. When it is a major structure, only the major structure name 1s speci- 
fied. 


SET (pointer_variable) 
Specifies a pointer variable that is set to the location of the storage allocated. 


The allocation is in storage associated with the run unit that processes the ALLO- 
CATE statement and persists until the run unit ends or until a corresponding FREE 
statement is processed. 


The amount of storage allocated for a based variable depends on its attributes, and 
on its dimensions, length, or size specifications. These attributes are determined 
from the declaration of the based variable. Based variables are always allocated in 
multiples of 16 bytes. 


FREE Statement for Based Variables 


The FREE statement frees the storage allocated for based variables. The syntax of 
the FREE statement for based variables 1s: 


eT ey 
pointer_variable —> 


pointer_variable — > 
The storage for a based variable is freed by specifying a pointer variable in the 
statement. If the based variable is not explicitly pointer-qualified, the pointer 
declared with the based variable is used to identify the storage freed. If no 
pointer has been declared, the statement is in error. 


based_variable 
Must be an unsubscripted, level-1 based variable. 


The amount of storage freed depends upon the attributes of the based variable, 
including bounds and/or lengths at the time the storage is freed, if applicable. When 
you free storage, you must be sure that the pointer you are using has the same value 
as the pointer you used to allocate storage, and that the based variable has the same 
attributes as the based variable you used when the storage was allocated. 


An error is raised for a FREE statement where the pointer variable addresses an 
automatic or static variable. 


Based Variables and Input/Output 


The following program segment shows how to use pointer variables and based 
structures to process different types of records in a file: 
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DECLARE TRANSFILE FILE RECORD INPUT, 
INRECORD CHARACTER (18), 
POINTER1 POINTER; 


DECLARE 1 DISPATCH BASED (POINTER1), 
5 RECORD CODE CHARACTER (1), 
5 PART.NO —- CHARACTER (7), 
5 QUANTITY CHARACTER (4), 
5 DEPT CHARACTER (2), 
5 PROJECT CHARACTER (4); 
DECLARE 1 RECEIPT BASED (POINTER1), 
5 RECORD CODE CHARACTER (1), 
5 PART.NO CHARACTER (7), 
5 QUANTITY CHARACTER (4), 
5 SUPPLIER CHARACTER (6); 
DECLARE 1 DISPATCH MSTRECORD, 
5 PART.NO — CHARACTER (7), 
5 QUANTITY CHARACTER (4), 
5 DEPT CHARACTER (2), 
5 PROJECT CHARACTER (4); 
DECLARE 1 RECEIPT MSTRECORD, 
5 PART.NO —- CHARACTER (7), 
5 QUANTITY CHARACTER (4), 
5 SUPPLIER CHARACTER (6); 


POINTER1 = ADDR(INRECORD) ; 
READ FILE (TRANSFILE) INTO (INRECORD) ; 
IF DISPATCH.RECORD CODE = 'D' 
THEN 
DISPATCH MSTRECORD 
= DISPATCH, BY NAME; 
ELSE IF RECEIPT.RECORD CODE = 'C' 
THEN 
RECEIPT MSTRECORD 
= RECEIPT, BY NAME; 
ELSE; 


In this example, the record descriptions DISPATCH and RECEIPT are both asso- 
ciated with POINTERI, which holds the address of INRECORD. Once a record 
has been read into INRECORD, RECORD _ CODE is tested to determine if a DIS- 
PATCH or RECEIPT record has been read. The appropriate fields are then 
assigned to DISPATCH _MSTRECORD or RECEIPT_MSTRECORD. If the 
record code for INRECORD is not valid, no action is processed. 


Data Assignment 


Conversions between any types of problem data are valid in assignments. 


Assignments are: 
« An assignment in an assignment statement 


e The initialization of a variable in a declaration 
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( . e An assignment to the control variable of a do-group 
¢ An assignment in a stream input or output operation 


¢ An assignment to a dummy argument when passing the dummy argument to a 
procedure or built-in subroutine 


¢ Returning a value from a function. 


Conversions may also be processed in comparisons, so that the items being com- 
pared have the same format. 


Before a value is assigned, it is converted to the type of the target. The precision or 
length of the target may differ from that of the converted source. The effect of dif- 
fering lengths or precisions is explained in the following sections. 


Cc String Data Assignment 


The source string is assigned to the target string. If the source string is longer than 
the target, excess characters or bits on the right are truncated. If the source string is 
shorter than the target, the value being assigned is padded on the right. Character 
values are padded with blanks, bit values with zeros. 


Examples are: 


DECLARE ACHAR CHARACTER(10); 
ACHAR = 'TRANSFORMATIONS'; 


c 'TRANSFORMATIONS'! has 15 characters. Therefore, five characters will be 
truncated from the right-hand end of the string when it is assigned to ACHAR. 
This is equivalent to 


ACHAR = 'TRANSFORMA'; 
The following statements assign equivalent values to ACHAR: 
ACHAR = 'PHYSICS!'s 


ACHAR = ‘PHYSICS  '; 
= The first assignment pads the character value on the nght with three blank charac- 
ters. 


The following statements assign equivalent values to ABIT: 


DECLARE ABIT BIT(10) ALIGNED; 
ABIT = '110011'B; 
ABIT = '1100110000'B; 


The first assignment pads the bit value on the right with four zeros. 


The following statements assign different values to ACHAR: 


ACHAR = '110011'B; 
ACHAR = '1100110000'B; 


Each assignment converts the bit constant to a character value. The first pads the 
value on the right with four blank characters and is equivalent to: 
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ACHAR = '110011 —'; 


The second is equivalent to: 
ACHAR = '1100110000'; 


The source string must not identify a string that starts to the left of and overlaps the 
target string. 


For example, the assignment: 
SUBSTR(ACHAR, 3,5) = SUBSTR(ACHAR, 1,5); 


is not valid, because the string identified by the SUBSTR built-in function starts to 
the left of the target string and overlaps it. 


Arithmetic Data Assignment 
A fixed-point target whose number of integer digits is smaller than that of the source 
may be too small to hold the source value, in which case the result is undefined. 
For example: 


DECLARE AFID FIXED DECIMAL (1) STATIC INITIAL (5), 
BFID FIXED DECIMAL (3,2), 
CFID FIXED DECIMAL (2,1); 


BFID = (AFID * 5) / CFID; 


In this example, the intermediate result of AFID+5 is 25. The result of dividing 25 
by the value of CFID fits the precision of the target BFID if the value of CFID is 
greater than 2.5, but loses significant digits if CFID is 2.5 or less. In both cases, the 
result may lose fractional digits. 


A fixed-point decimal target whose scale factor is smaller than that of the source 
loses digits on the right, starting with the least significant digit. For example: 


DECLARE AFID FIXED DECIMAL (5,3) STATIC 
INITIAL (12.987), 
BFID FIXED DECIMAL (5,1); 
BFID = AFID; 


In this example, the value of AFID is assigned to the target BFID. Because the 
scale factor of BFID is smaller than that of AFID, the fractional part of the value is 
truncated (it loses the two least significant digits), giving 12.9. To round a value, 
rather than let it be truncated, use the ROUND built-in function. 


If the number of integer digits of the source value is less than that of the target, the 
source value is padded with zeros on the left. Similarly, if the fractional part of the 
source value is smaller than that of the target, the source value is padded with zeros 
on the nght. For example: 
DECLARE AFID FIXED DECIMAL (3,1) STATIC 

INITIAL (12.3), 


BFID FIXED DECIMAL (5,2); 
BFID = AFID; 
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In this example, the value of AFID is assigned to BFID and padded on the night to 
the precision declared for BFID. The value of BFID is then represented as 012.30. 


If a source value is assigned to a floating-point target that has a smaller precision, 
the value of the target may be less accurate than the original source value. For 
example: 


DECLARE AFID FIXED DECIMAL (5) STATIC 
INITIAL (13579), 
BFLOD FLOAT DECIMAL (3); 
BFLOD = AFID; 


In this example, the value of AFID is converted to floating-point decimal with the 
maximum precision associated with short floating-point, and is assigned to BFLOD. 
However, the value of BFLOD is treated as having precision (3) whenever it 
requires conversion to a non-arithmetic data type. In that case, its value is repres- 
ented as 1.36 « 10««4. 


When you assign a scalar variable to a structure, the scalar is assigned to each field 
in the structure. Conversions are processed when necessary. Consider the following 
example: 


DECLARE CHARI CHARACTER (1) STATIC INITIAL ('0'); 
DECLARE 1 SAMPLESTRUCTURE, 

5 CHARFIELD CHARACTER (6), 

5 BINFIELD | BINARY FIXED (15), 

5 BITFIELD BIT (10) ALIGNED, 

5 PICFIELD PICTURE '9'; 


The assignment statement 
SAMPLESTRUCTURE = CHARI; 


would assign CHAR] to CHARFIELD, with five blank characters of padding to 
the nght. It would place the binary value zero in BINFIELD, the bit value zero in 
BITFIELD, and the EBcDIc character value '0' in PICFIELD. 


Data Conversion 
Data conversion may occur between any types of problem data, but may not occur 
between different types of program control data. 
Problem data may be converted in the following circumstances: 


e In an assignment (see “Data Assignment” on page 5-24 for the various types of 
assignment). 


e When passing an argument to a built-in function. 
¢ When using a conversion built-in function. 
¢ When evaluating an operational expression. 
Before a data item can be converted, all the data attributes of the target must be 


determined, including the length of a string target and the precision of an arithmetic 
target. 
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Built-In Conversion Functions 
You can convert problem data from one type to another by means of one of the 
built-in conversion functions: 


BINARY DECIMAL 
BIT FIXED 
CHARACTER FLOAT 


These are described in Chapter 15, “Built-In Functions, Subroutines, and 
Pseudovariables.” 


Each function returns a value with the attribute specified by the function name. 


Before you use data as operands, you may have to convert them explicitly to the 
type required by the operator (see “Operational Expressions” on page 9-4). For 
example: 


DECLARE ACHAR CHARACTER (8) 
STATIC INITIAL('01111110') , 
ABIT BIT(8) STATIC ALIGNED 
INITIAL('10000001'B), 
BBIT BIT(16) ALIGNED; 
BBIT = BIT(ACHAR) || ABIT; 


In this example, the two strings concatenated, ACHAR and ABIT, are a character 
string and a bit string. One operand must therefore be converted to the data type of 
the other. In this example, the BIT built-in function converts the character operand 
to a bit operand. 


Similarly, for most arithmetic operators, if one operand is fixed-point decimal with a 
nonzero scale factor and the other 1s fixed-point binary, you must convert the binary 
operand to a decimal operand (see “Results of Arithmetic Operations” on 

page 9-5). For example: 


DECLARE AFID FIXED DECIMAL(7,2), 
BFID FIXED DECIMAL(8,2), 
CFIB FIXED BINARY(15); 

BFID = AFID + DECIMAL(CFIB); 


In this example, AFID and CFIB are incompatible because AFID has a nonzero 
scale factor. CFIB must therefore be converted to decimal, which is done here by 
means of the DECIMAL built-in function. 


Forcing a conversion may save processing time. When the types of arithmetic oper- 
ands give a result with a base or scale different from those of the target, you can 
avoid the final conversion by converting one operand. For example: 
DECLARE AFID FIXED DECIMAL(5) , 

BFID FIXED DECIMAL(6), 

CFIB FIXED BINARY(15); 
BFID = AFID + DECIMAL(CFIB); 


In this example, the operands are compatible, as AFID has a scale factor of zero. 
Without the forced conversion of CFIB to decimal, AFID would be converted to 
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binary, and the result of the operation would be converted to decimal. By con- 
verting CFIB to decimal, one conversion is avoided. 


The conversions done by the conversion built-in functions can also be done by 
assignment to a variable that has the required attributes. You may, however, find 
the built-in functions more convenient than creating a variable just for a conversion. 


Calculating String Length and Precision 
In the following cases, the target’s length or precision is calculated first: 


¢ When converting an operand before processing an arithmetic or comparison 
operation. 


¢ When converting arguments of certain built-in functions before calling them. 


e When converting a data item from arithmetic to string. For example, conver- 
sion from fixed-point decimal to bit involves an initial conversion to fixed-point 
binary. 

e When converting an arithmetic or bit argument to character, before passing it to 
a parameter declared as CHARACTER(s), or when converting an arithmetic or 
character argument to bit, before passing it to a parameter declared as BIT(+). 


Conversion Rules 
This section gives the rules for conversion and explains when and how the precision 


of a target is calculated. The rules are given according to the data attributes of the 
target and source. 


Target: Arithmetic 


SOURCE: 


Arithmetic 
Conversion 1s necessary only when the source and target differ in base or scale. 


The target’s precision is calculated when any of the cases given under “Calcu- 
lating String Length and Precision” applies. The equations used in these con- 
versions are given in Figure 12-4 on page 12-27. 


BINARY FIXED | DECIMAL FIXED | BINARY FLOAT | DECIMAL FLOAT 
or PICTURE source source 
source 


BINARY P2= min(ceil 
FIXED (p) *3.32) + 1,31) (see note 3) (see note 3) 
target q2= 0 (see note 2) 


Figure 5-6 (Part 1 of 2). Equations for Calculating Converted Precision 
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BINARY FIXED | DECIMAL FIXED | BINARY FLOAT | DECIMAL FLOAT 


source 


P2 = ceil 
(p,/3.32) + 1 
q2= 0 
BINARY 
FLOAT 


ae 
ceil(p,/3.32) 


or PICTURE source source 
source 


(see note 4) (see note 3) 
Pz = min(ceil 
P2 = ceil(p, +3.32) (p, +*3.32),53) 
p= 


‘ie 
ceul(p,/3.32) 


Figure 5-6 (Part 2 of 2). Equations for Calculating Converted Precision 


Note: 


V3 


p, is the number of digits of the source, p, is the number of digits of the 
target, and q, is the target’s scale factor. 


. min(x,y) is the smaller of x and y. 


3. For a table of ceil values, see Figure 9-4 on page 9-8. 


5. 
6. 


. The scale factor of the source must be zero. If the number of digits of the 


source is greater than 9, and the number of binary digits needed is greater 
than the maximum, 31, the result may be undefined. 


If this conversion occurs, the target precision is always known. 


If the source is picture, p.=p, and q,=q). 


Conversion to a pictured target occurs only when data is assigned; in such cases, 
the target’s precision is always known. 


The equations in Figure 12-4 may also help you decide what precisions to give 
to variables. For example, the precision of a fixed-point decimal or pictured 
target in an assignment statement should be large enough to hold the maximum 
value of the source: 


For fixed-point binary (p,), the equation in Figure 5-6 on page 5-29 
p> = ceil (p,/3.32)+1 
gives the minimum number of decimal digits needed to represent p, binary 


digits. If you want a target scale factor of q», derive the number of digits, 
P2, from the formula 


Py = ceil (p,/3.32)+1+q, 


For fixed-point decimal (p,,q,), derive the precision and scale factor (p2,q2) 
from the formulas 


P2 = Pi -q tq 
G2 = q 


For floating-point binary (p,), derive the precision (p2) from the formula 
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p, 2 ceil (p,/3.32) 
¢ For floating-point decimal (p,), derive the precision (p,) from the formula 
Pz = Py 


¢ For a floating-point source, the exponent must be small enough for the 
source value to fit the target. 


The accuracy of a value may be affected when converting between binary and 
decimal representations. These conversions use the factor 3.32 when calculating 
the target precision. 


CHARACTER 
Conversion from character to arithmetic is valid only in an assignment or when 
using the BINARY, DECIMAL, FIXED, or FLOAT built-in functions. 


The source character value must represent an optionally signed arithmetic con- 
stant. It may be surrounded by blanks, but no blanks may appear between the 
sign and the constant. A null string or a string of blanks is permitted and is 
interpreted as a value of zero. 


If the source string does not satisfy these conditions, the conversion condition is 
raised. 


The numeric value represented by the optionally signed constant is converted to 
the attributes of the target, using the attributes of the constant as source attri- 
butes. 


BIT 
Conversion from bit to arithmetic is valid only in an assignment or when using 
the BINARY, DECIMAL, FIXED, or FLOAT built-in functions. 


The source bit value is interpreted as an unsigned binary integer and is con- 
verted to the attributes of the target, using FIXED BINARY as the source attn- 
butes. A null bit value is interpreted as a value of zero. 


Target: Character 


Conversion to character is valid only in an assignment or when using the CHAR- 
ACTER built-in function. 


SOURCE: 


Coded Arithmetic 
The number of digits of an arithmetic value that 1s converted to a character 
value must be greater than or equal to the scale factor. 


The coded arithmetic value is represented as a decimal constant, preceded by a 
minus sign if it is negative, as described below. The constant is converted to an 
intermediate character result whose length is derived from the attributes of the 
source. The intermediate result is assigned to the target according to the rules 
for string assignment. 


FIXED BINARY (p,) 
The binary precision (p,) is first converted to the equivalent decimal precision 
(p>,0), where 
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p9=ceil (p,/3.32)+1 


Thereafter, the rules are the same as for FIXED DECIMAL to CHARACTER. 


FIXED DECIMAL (p,,q,) 
Conversion is done in the following way: 


1. The constant is right adjusted in a field whose width is p, + 1 (The three 
added bytes allow for a minus sign, a decimal point, and a leading zero 
before the point.) 


2. Leading zeros to the left of the decimal point are replaced by blanks, except 
for the rightmost zero if it immediately precedes the decimal point. 


3. A minus sign precedes the first digit of a negative value. A positive value is 
unsigned. 


4. If q, > 0, a decimal point appears and the constant has q, fractional digits; if 
q,; =9, no decimal point appears. 


The following examples show the intermediate strings generated from fixed- 
point decimal values. The letter b indicates a blank character. 


'bbbb2947! 


"b-121.7' 
'-0.2000' 


FLOAT BINARY (p,) 
The floating-point binary precision (p,) is first converted to the equivalent 
floating-point decimal precision (p,), where p,=ceil(p,/3.32). Thereafter, the 
rules are the same as for FLOAT DECIMAL to CHARACTER. 


FLOAT DECIMAL (p,) 
A floating-point decimal source is converted as if it were transmitted by an 
E-format item of the form: 


E(w,d) 
where: 


Ww 
is the length of the intermediate string, p, + 7. 


is the number of fractional digits, p,-1. 


The following examples show the intermediate strings generated from floating- 
point decimal values: 
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1735 » 10%%5 'b1.7350E + 08b' 
-.001663 '-1.6630E-03b' 


l 'b1.00E + 00b' 
0 'b0.E+ 00b! 
25 « 10«4-101 'b2.50E-100! 


PICTURE 
The character value of the pictured field is assigned to the target string according 
to the rules for string assignment. 


BIT 
'0'B becomes the character 0 and '1'B becomes the character 1. The null bit 
string becomes the null character string. The obtained character value is 
assigned to the target string according to the rules for string assignment. 


Target: Bit 


Conversion to bit is valid only in an assignment or when using the BIT built-in 
function. 


SOURCE: 


Arithmetic 
If necessary, the arithmetic value is converted to binary fixed-point, and both 
the sign and any fractional part are ignored. The resulting binary integer is 
treated as a bit value. It is assigned to the target according to the rules for string 
assignment. 


FIXED BINARY (p,) 
The result is a bit string of length p,. If p, is zero, the result is the null bit 
string. 


The following examples show the intermediate strings generated from fixed- 
point binary values: 


[Predion [Vas [Sting 
(1) 1 '1'B 
(3) 3 '011'B 


FIXED DECIMAL (p,,q,) and PICTURE 
The fixed-point decimal value of a pictured field is used; its precision is taken 
from the corresponding picture specification. 


The length of the intermediate bit value 1s given by 
min(ceil ((p,-q,)+*3. 32) ,31) 


Only the number of integer digits of the source is used in this conversion; any 
fractional digits are ignored. The number of integer digits is p,-q,. (p, = q 
results in a null bit string.) 
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The following examples show the intermediate strings generated from fixed- 
point decimal values: 


[Precision [Value [String 
(1) 2 '0010'B 
(2,1) 2.2 '0010'B 


Fractional digits are lost. 


FLOAT BINARY (p,) 
The length of the intermediate bit value is given by 


min(31,p,) 


FLOAT DECIMAL (p,) 
The length of the intermediate bit value is given by 


min(ceil (p,*3.32) ,31) 


CHARACTER 
Character 0 becomes '0'B and character 1 becomes '1'B. Any character other 
than 0 or | raises the conversion condition. The null character string becomes 
the null bit string. The generated bit value, which has the same length as the 
source character value, is assigned to the target according to the rules for string 
assignment. 


Truncation of Floating-Point Data 


If a PL/I statement involves conversion of a floating-point data item in which the 
digits in the original copy of the data item will not all fit into the converted copy, 
then the rightmost excess digits are truncated. Such truncation can occur when con- 
verting floating-point data items from long form to short form, or from floating- 
point to fixed-point or picture data. 


In some kinds of conversions, such as from floating-point to character, an interme- 
diate conversion from floating-point to fixed-point is done, followed by a final con- 
version from fixed-point to character. Truncation can occur during the intermediate 
conversion. 


Examples of Data Conversion 


The following example shows the values obtained when assigning decimal integer 
and bit constants to bit variables. 
DECLARE ABIT BIT (1) ALIGNED, 
BBIT BIT (5) ALIGNED; 
ABIT=1; /*ABIT HAS VALUE '0'Bs/ 
BBIT=1; /*BBIT HAS VALUE '00010'Bs/ 
BBIT='1'B; /»*BBIT HAS VALUE '10000'Bs/ 


The assignment to ABIT results in the following sequence of actions: 


1. The decimal constant | has the attributes FIXED DECIMAL (1,0) and is con- 
verted to a fixed-point binary value of precision (4), following the ruies for con- 
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version from fixed-point decimal to fixed-point binary. The value is now 1, 
represented as a 4-digit binary number. 


2. This value is converted to a bit value of length 4 and becomes '0001'B. 


3. The bit value is assigned to ABIT. Because the length of ABIT is 1 and the 
length of the bit value assigned is 4, the value is truncated on the right. ABIT 
has a final value of '0'B. 


In the first assignment to BBIT, the sequence of actions is similar to that described 
for ABIT, except that the value is extended at the right with a zero, because the 
length of BBIT is one greater than that of the value to be assigned. 


The following example shows the values obtained when assigning character and 
integer constants to character variables: 


DECLARE ACHAR CHARACTER (4), 

BCHAR CHARACTER (7); 
ACHAR='0'; /*ACHAR HAS VALUE 'Q = 'x/ 
ACHAR=0; /xACHAR HAS VALUE ' Q'x/ 
BCHAR=1234567; /«*BCHAR HAS VALUE ' 1234'«/ 


In the first assignment, the character constant '0' is assigned to ACHAR and 
padded on the right with blanks. 


In the second assignment, the integer constant 0 has the attributes FIXED 
DECIMAL(1,0). It is converted to a character value, which introduces three blanks 
on the left, and assigned to ACHAR. 


In the third assignment, the integer constant is converted to the character value 
1234567. This value is truncated on the right and assigned to BCHAR. 
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Chapter 6. AS/400 PL/I File and Record Management 


This chapter gives an overview of the concepts involved in using AS/400 files. 
Topics include: 


¢ File management 
¢ Types of files 
¢ Using record formats. 


Detailed information about PL/I input/output is given in Chapter 8, “Using AS/400 
Files.” This includes specific information about commitment control and the 
%INCLUDE directive. Complete information on AS/400 files can be found in the 
Programming: Data Management Guide. 


c 


File Management 


Files and their use are controlled by OS/400. This section describes file independ- 
ence, device independence, system override considerations, security, and authority. 


File Independence 
The key element for all input/output operations on the AS/400 System is the file. 
All files used on the system are defined to OS/400. OS/400 maintains a description 
C of each file that is accessed by a program when the file is used. 


The files are online and serve as the connecting link between a program and the 
data. The actual device association is made when the file is processed. In some 
instances, this type of input/output control allows the user to change the attributes 
of the file used in a program without changing the program. 


PL/I files and AS/400 files are associated either by default, by the use of the TITLE 
. option of the OPEN statement, or by the use of a CL override command, such as 
Cc OVRTPEEF or OVRPRTE. For further information on the CL overnde commands, 
see the Programming: Control Language Reference. 


There are a few cases of file dependence. For example, the INTERACTIVE option 
of the ENVIRONMENT attribute usually implies a display file, and the INDEXED 
option implies a keyed data base file. 


Device Independence 
PL/I is, to a large extent, device independent. For example, if you specify the CON- 
SECUTIVE option of the ENVIRONMENT attribute, and do not use the 
OPTIONS option of the input/output statements, you can associate your PL/I file 
with any AS/400 device. 
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Spooling 


The AS/400 System provides for the use of input and output spooling functions. 
Each AS/400 printer and diskette description contains a spool attribute that deter- 
mines if spooling is used for the file at run time. The PL/I program is not aware that 
spooling is being used. The actual physical device from which a file is read or to 
which a file is written is determined by the spool reader or the spool writer. See the 
Programming: Data Management Guide for more information on spooling. 


Output Spooling 
Output spooling is valid for batch and interactive jobs. 


File override commands can be used at run time to override the spooling options 
that are specified in the file description, such as the number of copies printed. In 
addition, AS/400 spooling support allows you to redirect a file after the program has 
run. For example, you can direct the printer output to a different device, such as 
diskette. 


Input Spooling 


Input spooling is valid only for inline data files in batch jobs. If the input data read 
by PL/I comes from a spooled file, PL/I 1s not aware of which device the data was 
spooled in from. See the Programming: Data Management Guide for more infor- 
mation on inline files. 


System Override Considerations 
CL system override commands, such as OVRTPEF or OVRPRTF, may be used for 
several reasons: 


¢ To change or add file attributes. 
¢ To redirect a PL/I file to a different AS/400 file at run time. 


The name you specify on the FILE option of the override command is used to 
match the file name in either the file declaration or the TITLE option of the OPEN 
statement. For a discussion of how to use system override commands, refer to the 
Programming: Data Management Guide. 


If you issue the CL command OVRDBEF (Override Data Base File) for a PL/i file 
specifying a value for the MBR parameter, any member name you specify using 
TITLE in the OPEN statement for the file is ignored. Similarly, a CL override 
command for a PL/I file may override some of the ENVIRONMENT attribute 
options specified for the file. An example of an option that may be overridden that 
is also directly specifiable within the PL/I program is *EXCL or *EXCLRD lock 
state on data base files. 


Before a file can be accessed, you may need to specify additional file attributes on 
either an override command or a create or change system object command. 
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Overrides may be used to direct PL/I input and output to a different file than the 
program intended. For example, a PL/I file with the attributes of SEQUENTIAL, 
INPUT, and CONSECUTIVE could be used with a data base file, a tape file, a 
diskette file, or an inline file. 


When file redirection is used, you must ensure that the program is not attempting 
any I/O statement options that are not defined for the file type. For example, if the 
program is using POSITION(PREVIOUS) on a READ statement to a data base 
file, the file in the program cannot be directed to a diskette file. 


In general, input/output statement options not allowed for the file type will result in 
the ERROR condition being raised. The exceptions to these are the RECORD and 
INDICATORS options which are ignored by file types that do not support these 
options. For example, the RECORD option is ignored by diskette files, and the 
INDICATORS option is ignored by physical and logical data base files. 


Authority and ownership apply to a data base file on a file level. That is, if a user 
profile has a certain authority to a data base file, then that user may do the author- 
ized functions on any and all members of the file. 


Ownership 


Ownership of a file and authorization to it interact in the following ways: 
¢ An owner of a file always gets all rights to the file. 


e An owner’s rights can be revoked; but even when the owner has no explicit 
rights to the file, the owner may process GRTOBJAUT and RVKOBJAUT 
commands on it. 


e Changing the owner does not revoke the old owner’s rights to the file. 


Authority 


There are three Object Rights for a file: *OBJOPR, *OBJEXIST, and *OBJMGT. 
The four Data Rights for a file are: *READ, *ADD, *UPD, and *DLT. 
*CHANGE authority for a logical file is defined as *OBJOPR and for a physical file 
itis *OBJOPR plus all of the data nights. 


The following rules for data rights allow the user to protect a data base: 


e Data rights apply only to a physical file. An attempt to grant data rights to a 
logical file is ignored. 


e A file cannot be opened without *OBJOPR night to the target file (either phys- 
ical or logical). After the file is open, an I/O operation will not work without 
the corresponding data right on the physical file that contains the data. 


e The AUT parameter allows you to specify what authority the public has for the 
program. You can use AUT to specify a number of different types of pro- 
tection. 
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Types of Files 
The following AS/400 files are supported by AS/400 PLjI: 


¢ Data Base Files 

« Display Files 

¢ Diskette Files 

e« Tape Files 

¢ Printer Files 

¢ Data File Management (DDM) Files. 


The following AS/400 files are supported by System/38 Environment only: 


¢ Communications Files 
¢ BSC Files 
e Inline Files. 


The following sections introduce each type. For more information, see the 
Programming: Data Management Guide. 


Data Base Files 
A data base file is a collection of records. The sequence of these records and the 
fields contained in a record are a part of the system file definition. The fact that the 
field definition is part of the file definition is one of the features of the AS/400 archi- 
tecture. A physical file stores records in the same format and/or sequence in which 
you can access them. A logical file allows you to specify a description of how the 
records in a physical file may be accessed. 


Physical Files 
A physical file contains fixed-length records with one record format. The records 


are physically stored in arrival sequence. You may access these records in either a 
specified keyed sequence or arrival sequence. 


Logical Files 
A logical file does not contain records, but contains a set of instructions that the 
system uses to access a physical file. A logical file allows you to define different 


views of the fields in the records in a physical file, and to define different sequences 
for accessing these records. 


File Organization 


The AS/400 data base file organization is based on arrival sequence or keyed 
sequence access paths. 


Access Paths 


The access path determines the order in which the data records are returned to the 
program when a file is accessed. 
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Arrival Sequence Access Path: An arrival sequence access path is based on the 
order in which the records are stored in the file. For retrieval or updating, records 
can be accessed in one of the following ways: 


¢ Sequentially, where each record is taken from the next sequential position in the 
file. 


e Directly by relative record number, where the record is identified by its position 
from the beginning of the file. 


An arrival sequence access path is valid only for the following: 
¢ A member of a physical file, where no key fields are specified. 


¢ A logical file in which each member of the logical file is based on only one 
member of only one physical file, where no key fields are specified. 


Keyed Sequence Access Path: For a keyed sequence access path, the sequence of 
the records in a file 1s based on the contents of the key fields as defined in the DDS 
(Data Description Specifications). This type of access path is updated whenever 
records are added, deleted, or changed. 


For retrieval or updating, records can be accessed in one of the following ways: 


¢ Sequentially, where each record is taken from the next sequential position in the 


file. 


e Directly by relative record number, where the record is identified by its position 
from the beginning of the file. 


e Directly by means of the key fields as defined in the DDs. 


The keyed sequence access path is valid for any physical or logical data base file 
type. The sequencing of records in the file is defined in the DDs for the file when 
the file is created and 1s maintained automatically. 


Record Formats 


A record format definition is a list of names and attributes of fields in the order in 
which they should appear in a record. This definition is made through Dps, and 
includes the field name, the data type (binary, packed decimal, floating-point, zoned 
decimal, or character), and the length of the field. Files use record formats in the 
following ways: 


e A physical file has one record format. This record format determines the actual 
storage attributes and order of the fields for the records in the file. 


e A logical file associates record formats with based-on physical file(s) and 
member(s). A logical record format defines a logical view of records in the 
physical file. The fields in a physical record format map to the fields in the 
logical record format. 
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File Locking 


Members 


In the discussion so far, a data base file has been considered a means of accessing a 
collection of records. It is more accurate to say that a collection of records is 
accessed with a member of the file. 


The ability to have many members within a file allows you to describe data charac- 
teristics once at the file level, then operationally separate collections of records 
created, each having these same characteristics. Therefore: 


¢ A file may be defined to allow any number of members. 
¢ Members can be added to and deleted from a file. 


¢ Each physical member consists of a separate stored collection of records with an 
independent arrival sequence. 


¢ Each keyed member consists of a separate access path over the data in physical 
file members. Therefore maintenance is done on a member basis. 


If a file is defined with a maximum of one member, the fact that the file actually has 
a member makes no difference to the user. This is the case because the first 
member of a file is the default member used in operations when no member name is 
specified. 


If a file is overridden with the CL command OVRDBF specifying MBR(*ALL), all 
the members in the file are processed, one at a time, in the order they were ori- 
ginally created. After the last member is processed, an ENDFILE condition is 
raised. If you specify the POSITION parameter of the READ statement with 
NXTUNQ, PRVUNQ, NXTEQL, PRVEQL, FIRST, or LAST, the search for the 
record will be made only within the member currently being accessed. 


File locking is used to control the access to physical file members. If more than one 
job is running at the same time, and all are accessing the same physical file 
members, some degree of file locking may be necessary in order to synchronize the 
use of the data. 


There are five different lock states that may be applied to the records in a physical 
file member. When a particular lock is specified, all of the data records in each 
physical file member associated with the member being opened are locked in the 
specified state. For logical file members, this means that all of the data records in 
all of the base physical file members are locked in the specified state. The file lock 
States are: 


e Exclusive (*EXCL) 

e Exclusive Allow Read (*EXCLRD) 
e Shared for Update (*SHRUPD) 

e Shared No Update (*SHRNUP) 

e Shared for Read (*SHRRD). 


For a definition of these lock states, refer to the Programming: Data Management 
Guide. 
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You may specify or imply all but the *SHRNUP lock state from within a PL/I 
program. *EXCL or *EXCLRD may be specified as options on the ENVIRON- 
MENT attribute. *SHRUPD is the default for a file with the UPDATE or 
OUTPUT attribute specified, and no lock state specified in the ENVIRONMENT 
attribute. *SHRRD is the default for a file with the INPUT attribute specified, and 
no lock state specified on the ENVIRONMENT attribute. 


Notes: 


1. File locks are not checked from within one running job. File locks only prevent 
access from other concurrently running jobs. This means that from within one 
running job, a file with *EXCLRD may be opened more than once. 


2. The CL command OVRDBF (Override Data Base File) may override the lock 
state specified or implied by the PL/I program. 


Record locking is used to control the updating of records within data base files. A 
record lock is similar to an *EXCLRD lock on a file. The user holding the record 
lock has exclusive update rights to the record, but other users may read the record. 
(Reading a locked record under commitment control may not be allowed. See 
“Using the PLICOMMIT Built-In Subroutine” on page 8-59.) 


Locks apply only to records in physical files. A record in a logical file is always 
mapped to a particular record in a physical file. Locks are maintained on a physical 
record by each logical or physical file. If a record is accessed by two different files, 
the second file to access the record will find the record already locked. Because only 
physical records are locked, there may be many records in different logical files that 
all map to the same physical record. You must be aware of which physical files are 
used by the various logical files and ensure that all files are used in a consistent 
manner. 


When a READ statement is processed for a file with the UPDATE attribute, the 
record just read will be locked. If the record is already locked to another concur- 
rently running job, the READ statement will wait until either the record lock 1s 
released or a record lock wait timeout occurs. Ifa record lock wait timeout occurs, 
the TRANSMIT condition is raised. The record lock wait time defaults to 60 
seconds but may be set by the user through the create file or override commands. 


A record lock is normally released whenever another READ, REWRITE, or 
DELETE statement is directed to a different record in the same open PL/I file. If 
another READ statement is processed to the same record in the same open PL/I file, 
the record lock is not released. If a REWRITE or DELETE is directed to a record 
just read for UPDATE in the same open PL/I file, the record lock is released after 
the REWRITE or DELETE statement is processed. 


The record lock held after a READ statement will be released if a subsequent 
READ statement ends with a KEY condition. You may use this fact to release a 
record lock by forcing a KEY condition to occur. Ifa record is locked to a file and 
you do not release the lock through the use of a subsequent READ, REWRITE, or 
DELETE statement, the record will remain locked to the file until either you issue a 
CLOSE statement, or the file is closed by PL/I at the end of the main procedure. 
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DEVICE Files 


DISPLAY Files 


A REWRITE or DELETE statement with the KEY option attempts to obtain a 
record lock prior to the REWRITE or DELETE operation. This means that a 
REWRITE or DELETE statement may wait if the record is already locked. If the 
record lock timeout occurs, the REWRITE or DELETE statement will end with 
TRANSMIT condition. 


Note that unlike file locks, record locks are checked within the same running job. 
This means that it is possible to receive a record locked condition on a record that is 
locked within the same job. This can occur if the same physical file record is 
accessed for UPDATE through different PL/I files. If this occurs, the READ state- 
ment ends immediately with TRANSMIT condition. The record wait time is not 
used in this case. 


If commitment control is active for a file, the releasing of record locks is delayed 
until a call to PLICOMMIT or PLIROLLBACK is processed. For the rules on 
record locks under commitment control, see ‘Record Locks” on page 8-62. 


A device file is a description of how input data is presented to a program from a 
device, or how output data is presented to the device from a program. It is not 
necessary to have a separate device file for each device; you can use only a single 
device file for several different devices of the same class by using an override 
command. Any number of device files can be associated with one device, but only 
one device description can exist for each device. For more information on device 
descriptions, see the Programming: Data Management Guide. 


The types of device files supported by PL/I are: 


¢ Display Device Files 
¢ Diskette Files 

e Tape Files 

¢ Printer Files 

° DDM Files. 


The types of device files supported by PL/I in System/38 Environment only are: 


e Communications Files 
e BSC Files. 


Display device files are used to format the display. They describe input and output 
fields, constants, the use of command function and command attention keys, and 
the handling of errors. Display files can be program-described files or externally 
described files. 
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Subfiles 


A subfile is a group of identically formatted records that is read from or written to a 
display device file. Subfiles can be specified in the DDs for a display device file to 
allow the user to handle multiple records of the same type on the display. For 
example, a program reads records from a data base file and creates a subfile of 
output records. When the entire subfile has been written, the program sends the 
entire subfile to the display device in one write operation. The user can change data 
or enter additional data in the subfile. The program then reads the entire subfile 
from the display device into the program and processes each record in the subfile 
individually. 


Descriptions of records included in a subfile are specified in the DDs for the file. 
The number of records that can be contained in a subfile must also be specified in 
the DpDs. One file can contain more than one subfile, and up to twelve subfiles can 
be active and displayed concurrently. 


The pps for a subfile consists of two record formats: a subfile record format and a 
subfile control record format. The subfile record format contains the field 
descriptions of all the records in the subfile. Specification of the subfile control 
record format on the READ or WRITE statement causes the physical read, write, 
or setup operations of a subfile to take place. 


For a description of how the records in a subfile can be displayed and for a 
description of the keywords that can be specified for a subfile, see the Programming: 
Data Description Specifications Reference. 

Some typical uses of subfiles include: 


¢ Display only. The user reviews the display. 


¢ Display with selection. The user requests more information about one of the 
items on the display. 


¢ Modification. The user modifies one or more of the records. 


¢ Input only, with no validity checking. A subfile is used for a data entry func- 
tion, and the records are not checked. 


¢ Input only, with validity checking. A subfile is used for a data entry function, 
but the records are checked. 


¢ Combination of tasks. A subfile can be used as a display with modification. 


Other Types of Device Files 
Other types of device files include: 


DDM files 
Communications files 
BSC files 

Inline files. 
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DDM Files J 


Distributed Data Management (DDM) allows you to access data files that reside on 
personal computers or on remote IBM System/370, System/36, System/38, and 
AS/400 Systems. The PL/I compiler supports DDM files. You can retrieve, add, 
update or delete data records in a file that resides on another system. In addition, a 
remote system can access your AS/400 data base for record retrieval. 


To use DDM files with PL/I programs, some important considerations are: 


e When a DPM file is accessed as the source file for a PL/I program, the margins 
used in the compilation of the PL/I source are the default values of 2 and 72. 
No other margin values can be specified. 


For more information about accessing remote files, refer to the Communications: 
Distributed Data Management User's Guide. ; 


Communications and BSC Files 


A communications file is a device file used to support Synchronous Data Link 
Control (SDLC) protocols. A Bsc file is a device file used to support Binary Syn- 
chronous Communications, a form of communications line control that uses trans- 
mission control characters to control the transfer of data over a communication line. 


Inline Files ) 


An inline data file is a data file that is included as part of a batch job when the job 
is read by a reader or by the CL commands SBMDBJOB and SBMDKTJOB. For 
further information on these commands, see the Programming: Control Language 
Reference. An inline data file is delimited within the job by a //DATA command at 
the beginning of the file and by an end-of-data delimiter (a user-defined character 
string or the default of //) at the end of the file. 


The record length for inline files is 80 bytes for a data file and 92 bytes for a source 
file. ) 


An inline data file can be either named or unnamed. For an unnamed inline data 
file, either QINLINE is specified as the file name in the //DATA command or no 
name is specified. For a named inline data file, a file name is specified. 


A named inline data file has the following characteristics: 


¢ It has a unique name within a job; no other inline file can have the same name. 
e Jt can be used more than once in a job. 
¢ Each time it is opened, it is positioned to the first record. 
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Using Record Formats 


A file record format must be defined to the system before you can use it in your 
programs. This can be done in two ways — externally described and program- 
described. Data base, display, communications, BSC, and printer files may be either 
externally described or program-described. Diskette, inline, and tape files can only 
be program-described. 


Note that actual file processing within the PL/I program is the same if the file is 
externally described or program-described. 


Externally Described Record Formats 


An externally described file is described at the field level to OS/400 through Dps. 
The description includes information about the type of file, such as data base or a 
device, and a description of each field and its attributes. 


By using the “INCLUDE directive, you can bring the external descriptions of a 
record’s fields and attributes into your program and, therefore, you will not have to 
define them in your program. (See “Using the % INCLUDE Directive for External 
File Descriptions” on page 8-73.) 


Externally described files offer the following advantages: 


¢ Less coding in PL/I programs. If the same file is used by many programs, the 
fields can be defined once to OS/400 and used by all the programs. This elimi- 
nates the need to code record descriptions for PL/I programs that use externally 
described files. 


¢ Less maintenance activity when the file’s record format is changed. You can 
often update programs by changing the file’s record format and then recompiling 
the programs that use the files without changing any coding in the program. 


¢ Improved documentation because programs using the same files use consistent 
record format and field names. 


Defining Record Formats with DDS 


Externally described data files are described using DDs (Data Description Specifica- 
tions). Using DDS, you provide descriptions of your files (including attributes of 
each field as well as record and file level information) used when the files are 
created. The Data Description Specifications form provides a common format for 
describing data externally. 


There are two methods of providing information with the Dps form. You specify 
information that is frequently required by using the fixed columns provided on the 
form. You specify information that is less frequently needed by using the appro- 
priate keywords and parameters. For example, the keyword DESCEND changes 
the sequencing of records from ascending (the normal sequence used by the system) 
to descending for a particular key field. 
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Level Checking 


When a PL/I program uses an externally described file, the AS/400 System provides 
a level check function. This function ensures that at run time the format has not 
changed since compilation time. 


If you specify the DESCRIBED option of the ENVIRONMENT attribute when 
you use the % INCLUDE directive to copy a record description of an externally 
described file into your program, level checking will occur for the copied record 
formats. 


The level check function can be requested on the CL create, change, and override file 
commands. The default on the create file command is to request level checking. If 
level checking was requested, level checking occurs on a record format basis when 
the file is opened. If a level check error occurs, an UNDEFINEDFILE condition 
occurs at OPEN time. 


If an existing format is used in a new file, any existing PL/I programs that use the 
format can still be used with the new file (assuming that no other conflicts such as a 
change of keys exist) without recompilation. 


For more information on how to specify level checking, see the Programming: 
Control Language Reference. 


Program-Described Files 
A program-described file 1s described within the PL/I program with DECLARE 
statements. The description of the file to OS/400 includes information about the 
type of file and the length of the records in the file. 
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Chapter 7. File Declaration and Input/Output 


This chapter provides information about features of PL/I that are specific to AS/400 
input/output. These features are discussed with reference to the ENVIRONMENT 
file declaration attribute, opening and closing files, and the OPTIONS option for 
input/output statements. 


The following shows the syntax for the DECLARE statement, and how the ENVI- 
RONMENT attribute fits into the overall file declaration. Refer to Chapter 12, 
“Declaring Names and Attributes of Variables” for more detailed information on the 
DECLARE statement. 


Dd attribute a at 
level al 
(——name ) 


Abbreviation: DCL for DECLARE. 


The ENVIRONMENT Attribute 


The ENVIRONMENT file declaration attribute allows you to specify information 
about implementation-defined features such as: 


¢ File organization 

e File characteristics 

¢ File locking 

e Commitment control 
e Level Checking. 


Options specified on the ENVIRONMENT attribute do not influence any default 
file attributes. 


The following examples show several different reasons for using ENVIRONMENT 
options: 
e An option may be required for successful data transmission. 


For example, you must specify the INTERACTIVE option before you can 
open a display file. 


e An option may be used to supply information. 


For example, you can use the BUFSIZE option to specify the record length of 
a file and override the system description of the file. 
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e An option may be used to check appropriate association of program and system 
functions. 


For example, when you specify the DESCRIBED option, the system processes 
level checking functions. See the Programming: Data Management Guide for a 
discussion of level checking. 


The syntax of the ENVIRONMENT attribute is: 


>>—ENVIRONMENT——( 


EXCLRD 


ak ae ac 
ime satanic tach aa aes 
anaes Sennen 5 See cer 
COMMITTABLE BLOCK NOINDARA 


The options are discussed in the following sections. 


File Organization Options 
The file organization options ae CONSECUTIVE, INDEXED, and INTERAC- 
TIVE. CONSECUTIVE is the default. 


CONSECUTIVE 
This indicates that records in the file are stored in a consecutive manner. A 
TAPE file for example, has CONSECUTIVE file organization. CONSEC- 
UTIVE 1s supported for all file types to increase device independence and allow 
for file redirection. 


If you specify CONSECUTIVE for a logical file member that is based on more 
than one physical file member, the UNDEFINEDFILE condition is raised 
when the file is opened. 

INDEXED 
This indicates that the keyed access path for a physical or logical data base file is 
used. 


You must explicitly code INDEXED to use a keyed sequence access path. If 
you do not code INDEXED, the default of CONSECUTIVE applies, the keyed 
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sequence access path is ignored, and the arrival sequence access path is used 
instead. 


INTERACTIVE 
This indicates that an interactive device is used. An interactive device is defined 
as either a display device or a remote program that is accessed through either a 
communications or BSC file. If you specify INTERACTIVE, you can use both 
READ and WRITE statements on a SEQUENTIAL UPDATE file. 


File Locking Options 


C Key Options 


The file locking options, EXCL and EXCLRD, control the lock type applied to a 
data base file. 


EXCL 
Specifies that programs in concurrently running jobs cannot access the file. 


EXCLRD 
Specifies that programs in concurrently running jobs cannot update the file, but 
may read from the file. 


These specifications apply to physical and logical data base files, not to display or 
device files. 


When you specify a file locking option, the file member is locked at the time the file 
is opened. The lock is only visible to other concurrently running jobs. When you 
specify a file locking option for a logical file, one or more members of one or more 
physical files are locked. 


If you do not specify one of these options, there will be a default lock on the file, 
depending on if the INPUT, OUTPUT, or UPDATE attribute is specified. If you 
specify the INPUT attribute, the default lock is shared read («SHRRD); if you 
specify the OUTPUT or UPDATE attribute, the default lock is shared update 
(sSHRUPD). See “File Locking” on page 6-6, and the Programming: Data Man- 
agement Guide for more information on file locking. 


The key options, KEYDISP and KEYLENGTH, move the KEYFROM variable 
on a WRITE statement or the KEY expression on a REWRITE statement into the 
record to ensure that the imbedded key and the associated key are of the same value 
when a WRITE or REWRITE statement is processed. 


For INDEXED organization with program-described files, you must specify 
KEYDISP and KEYLENGTH. Also, if you specify INDEXED, but do not 
specify DESCRIBED, you must specify KEYDISP and KEYLENGTH. 
KEYDISP and KEYLENGTH imply INDEXED. 


KEYFROM(expression) can be used on a WRITE statement only if KEYDISP 
and KEYLENGTH are specified. 
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CTLASA Option 


If KEYDISP and KEYLENGTH are specified, the KEYFROM variable will be 
moved into the RECORD prior to the WRITE. Also, the KEY expression is 
moved into the record prior to the REWRITE. 


KEYDISP (integer_constant) 
Describes where the key field is located in the record. If you specify KEYDISP, 
do not specify DESCRIBED, CONSECUTIVE, or INTERACTIVE. 


Use this option only for data base files in which all key fields are contiguous 
and each record format has the same key field definitions. KEYLENGTH must 
be specified when KEYDISP is specified. 


The integer_constant is the displacement of the key in the record. For example, 
KEYDISP(0) is the first byte of the record. KEYDISP(1) is the second byte. 


KEYLENGTH (integer_constant) 
Describes the key length for the data base file. KEYLENGTH must be speci- 
fied with KEYDISP. See KEYDISP above for details. KEYLENGTH must 
match the maximum key length for the data base file. 


The CTLASA option specifies that the first byte of each record is expected to be a 
print control character (i.e. ANSI forms control character). 


If you want to use this option, you must declare it explicitly. You are responsible 
for ensuring that the first byte of each record contains a valid print control char- 
acter. The printer file that you direct the output to must have CTLCHAR(*FCFC) 
specified on the CL commands CRTPRTF or OVRPRTF in order to produce 
printer spacing corresponding to the print control characters in the printer file. No 
compiler support is provided other than activating First Character Forms Control 
(FCFC) support at file open time. 


The valid print control characters are shown in the following table. 


Action 
(blank) Space | line before printing 


[0 | Space nes before pining 
[= Seace 3 nes before pining 


Skip to channel 3 
Skip to channel 4 
Skip to channel 5 


Figure 7-1 (Part 1 of 2). American National Standard Print Control Characters 
(CTLASA) 
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[6 [Sipio dammeté 
Skip to channel 7 
[a skip to anne 
Pg Skip to channel 9 
[8 | Skip te chanel 1 


Figure 7-1 (Part 2 of 2). American National Standard Print Control Characters 
(CTLASA) 


You can also use the CL command OVRPRTF (Override Printer File) to set 
channel and line numbers (refer to the Programming: Control Language Reference 
for details). 


Do not specify CTLASA for an externally described printer file. Use indicators 
instead of print control characters to provide spacing and other printer controls (see 
“Indicators” on page 8-76). 


BUFSIZE (integer_constant) Option 
The BUFSIZE option specifies a value that the program uses as the maximum 


record length for the file. The value specified is the input and output buffer length 
that is allocated for the file when it is opened. 


You must code BUFSIZE when creating a new file on a diskette device: BUFSIZE 
specifies the record length on the diskette. 


You can use the BUFSIZE option in the following ways: 


¢ To override the actual file record length without changing the file specification. 
¢ To specify the storage size in the system buffer. 
* To specify the record length when creating diskette files. 


If you do not specify BUFSIZE, the length of the input/output buffers is based on 
the maximum record length defined for the file. 


The INTO option of the READ statement controls the amount of data read into 
the input buffer, up to a maximum you can specify on the BUFSIZE option. 


The FROM option of a WRITE or REWRITE statement controls the amount of 
data written or rewritten from the output buffer, up to a maximum you can specify 
on the BUFSIZE option. 


When a READ statement with the SET option is processed, any buffer storage 
beyond the BUFSIZE value is undefined. 
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Note: If you specify the SET option of a READ statement, the program 
description of the record must match the actual records in the file, or unpredictable 
results may occur. There is a possibility of addressing beyond the end of the system 
input buffer, or if blocking is in effect, to address a portion of the next record in the 
buffer. To avoid this, specify the BUFSIZE option with a length equal to the 
longest record used for the file. This allows the redirection of the file to a file with a 
smaller record length at run time. 


For tape files, BUFSIZE corresponds to the RCDLEN parameter on the CL 
command CRTTAPF (Create Tape File) or OVRTAPF (Override Tape File). 
Refer to the Programming: Control Language Reference for a discussion of the 
restrictions of the RCDLEN parameter with tape files. 


DESCRIBED Option 


The DESCRIBED option indicates that external record format definitions from the 
AS/400 file object are being used within the program. 


The default is not to use DESCRIBED. 


When you specify DESCRIBED, the following functions occur: 


¢ Level checking is processed at time of file opening for all record formats associ- 
ated with this file that have been declared using the % INCLUDE directive. 


¢ Compile-time diagnostics are processed to ensure that the PL/I file attributes and 
system file attributes match. The valid combinations are shown in Figure 7-2 
on page 7-9. 


For files with indexed organization, you must ensure that the key is the same as the 
key in the replaced record. If DESCRIBED is specified and the values of the key 
fields in the record are not equal to the KEY expression, the results are unpredict- 
able. 


For DESCRIBED data base files, KEYFROM("*) must be coded on the WRITE 
statement when KEYFROM is used. 


Note: You can prevent level checking by specifying LVLCHK(*NO) on one of the 
appropriate Create xxx File (CRTxxxF) or Override xxx File (OVRxxxF) com- 
mands. For more information on level checking, refer to the descriptions of the 
above commands in the Programming: Control Language Reference. 


Commitment Control Option 


The COMMITTABLE option indicates that a logical or physical data base file is 
placed under commitment control. Commitment control allows the user to ensure 
that multiple changes to data base files are all either made permanent or cancelled as 
a single operation when a commitment boundary is reached. 


The default is not to ue COMMITTABLE. 


Use the COMMITTABLE option with the PLICOMMIT and PLIROLLBACK 
built-in subroutines (see ‘Using the PLICOMMIT Built-In Subroutine” on 
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page 8-59 and “Using the PLIROLLBACK Built-In Subroutine” on page 8-60) or 
their equivalents in other high level languages, or the CL commands STRCMTCTL 
(Start Commitment Control) and ENDCMTCTL (End Commitment Control). 
(See the Programming: Control Language Reference.) 


The UNDEFINEDFILE condition is raised if COMMITTABLE is specified and 
the file is not a data base file. 


The BLOCK option specifies blocking for data base files. 


If you specify BLOCK, you must not specify the OPTIONS option of the READ 
or WRITE statement. 


BLOCK can be specified to improve performance when the file is primarily accessed 
by READ statements without the KEY option, or WRITE statements without the 
KEYFROM option. 


When you specify BLOCK for an INPUT file, the complete block is transferred 
from the file to the input buffer. Records are read from the input buffer to the PL/I 
program, one at a time, until the buffer is empty. 


When you specify BLOCK for an OUTPUT file, records are written from the 
program to the output buffer, one at a time, until the block is full. Then the com- 
plete block is transferred to the file. 


The number of records in the block is optimized by the system and varies with each 
file type. Refer to the Programming: Data Management Guide for a description of 
the blocking support provided for each AS/400 file type. 


If your application requires an immediate view of the file after each input or output 
transaction, do not specify blocking. If blocking is in effect for an INPUT file, new 
records are only available after a complete block is read into the program. If 
blocking is in effect for an OUTPUT file, new records are only available after a 
complete block is written to the data base. Therefore, duplicate key conditions may 
not be detected until blocks are transferred, or until files are closed. Programs 
sharing files will have to wait for newly added records until a block is written. 


Even if you specify blocking, it is ignored under the following conditions: 


¢ If you specify the file attributes DIRECT with INPUT or UPDATE. 


¢ If you specify the ENVIRONMENT options INTERACTIVE or 
COMMITTABLE. 


¢ If you specify an AS/400 file type that does not support blocking. Only data 
base, tape, and diskette files support blocking. 


If you specify the BLOCK option for a data base file, and the option is ignored by 
OS/400, you will receive a diagnostic message when the file is opened. To find out 
when blocking is ignored for data base files, refer to the Programming: Control Lan- 
guage Programmer's Guide. 
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NOINDARA Option 
The NOINDARA option specifies that you are using indicators without the 
INDARA keyword specified in the pps for the file. 


If you specify NOINDARA, do not specify the INDICATORS option on record 
[/O statements. 


You must specify NOINDARA if you do not specify the DESCRIBED option of 
the ENVIRONMENT attribute and you do not specify INDARA in the DDs. 


NOINDARA indicates that the external description of the file does not contain the 
Dps keyword INDARA. If NOINDARA is specified, both program-described files 
and externally described files are assumed to have indicators located in the record 
buffer, and not in a separate area. If NOINDARA 1s not specified, it will be 
assumed that the INDARA keyword has been specified in the Dps for the file. See 
“Using Indicators in the Record Area” on page 8-49. 


If you specify DESCRIBED, PL/I will extract the file definition at compile time and 
use the information in the file to determine if INDARA 1s specified. 


Figure 7-2 summarizes the valid combinations of file attributes and ENVIRON- 


MENT options you can specify for the different types of AS/400 files. The figure 
notes explain how to use the figure. 
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Key: 
RECORD 


STREAM 


[x 4/ 


Footnotes: 


must be declared explicitly or 
implicitly 
default attribute or option 


default path 


comment 


‘STREAM and PRINT are not valid with an externally described print file. 
“If you specify CONSECUTIVE for a logical file member that is based on more 
than one physical file member, the UNDEFINEDFILE condition is raised 
when the file is opened. 

3File must have the EXTERNAL attribute. 

*BLOCK is ignored if you specify DIRECT INPUT or UPDATE. 
°CTLASA is not valid with an externally described print file. 

°Required for a diskette file with RECORD OUTPUT. 

"For physical and tape files, the forms control character is inserted in the first 
byte of each record by the PRINT attribute. 

®Diskette files with STREAM OUTPUT are not allowed because diskette files 
do not have a default record length and it is not possible to specify a record 
length for diskette files (the ENVIRONMENT attribute can not be used with 
the STREAM attribute). 


Additional Note: 


For a list of umplied attributes and options, see “Implied Attributes” on 


page 12-5. 


How To Use The Table 


Any line through the attributes and options in this table contains a complete set of 
the file description attributes for a name. By proceeding through the table, from top 
to bottom, you can select a valid combination of attributes and options for any line. 


¢ Attributes and options shown in boldface must be declared explicitly (in a 
DECLARE statement) or implicitly (through the use of another attribute, 
option or statement). The first attribute or option in boldface on any line is 
required if you want any attributes or options on that line. 


¢ Default attributes and options are underlined. They are selected for you, on the 
default path, unless you specify any alternative attnbutes or options (shown as 
branches from the default path). 


¢ All other attributes and options are optional. You must specify them if you 
want the declared name to have that particular attribute or option. 


¢ Exceptions to these points are discussed in the footnotes. 
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Opening and Closing Files 


Before a file can be used for input or output, it must be opened. Opening a file 
involves locating the AS/400 file object through the library search list, the library 
name specified in the TITLE parameter of the OPEN statement or library specified 
on a corresponding override CL command. If the attempted connection is unsuc- 
cessful, the UNDEFINEDFILE condition 1s raised. 


Scoping of Open Files (File Sharing) 


Files within PL/I programs may have either an EXTERNAL or INTERNAL attn- 
bute. If you do not specify the scope, the default is EXTERNAL. When you 
declare a file with the EXTERNAL attribute, the file name is known to all PL/I pro- 
cedures in the run unit. A file with the INTERNAL attribute can only be refer- 
enced in the block in which it is declared and in any blocks contained in the 
declaring block. 


This section describes how the PL/I attribute of an EXTERNAL or INTERNAL 
file interacts with the system in determining how and when a file is opened. The 
sharing described here is only from the perspective of sharing from within one run 
unit. The section concludes with some special considerations for opening stream 
files and closing files after an error. 


The first time a file is opened in a run unit, a new open data path (ODP) with a new 
invocation number is created for the file. Refer to the Programming: Data Man- 
agement Guide for a description of the ODP. 


Note: If you use the CL command RCLRSC (Reclaim Resource), you should be 
aware that this file belongs to the first PL/I procedure in the run unit, regardless of 
where it actually is located. Refer to the Programming: Control Language Refer- 
ence for a description of the RCLRSC command. 


Once a file is opened, additional OPEN statements for the file are ignored. The file 
retains the attributes with which it was first opened; no checking is processed to 
ensure that the attributes specified on the initial open are consistent with those spec- 
ified on the OPEN statement that 1s ignored. 


Once a file is opened, it remains open until one of the following occurs: 


¢ You issue a CLOSE statement for the file. 
¢ The run unit ends, and closes all the open files. 


A file declared with the EXTERNAL attribute can be shared by programs in dif- 
ferent run units if you specify SHARE(*YES) when you create the file. The file will 
remain open until the last program closes the file. If a file is closed following a run 
time error (see “Considerations for File Closing after an Error” on page 7-13), the 
actual closing of the file will not occur until all other concurrently running jobs 
using the file also issue close commands. 


A file declared with the INTERNAL attribute cannot be shared, therefore you 
should specify SHARE(«NO) when you create the file. Even if you attempt to 
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open an INTERNAL file with SHARE(+YES), the file is opened with ) 
SHARE(«NO). 


Note: If you attempt to open an INTERNAL file that has specified 
SHARE(+YES), and that is already open within the job, the UNDEFINEDFILE 
condition is raised. 


All INTERNAL PLy! files have their own separate connections to data management. 
Therefore, each INTERNAL file maintains its own file position, control informa- 
tion, and record buffers. All EXTERNAL files have one connection to data man- 
agement. Therefore, all external files share the same control information, file 
position, and record buffers. 


The set of records manipulated by either an INTERNAL or EXTERNAL file is 

established at the time the data management connection is made. This connection 

is made the first time the file 1s opened within the run unit. These rules are the | 
same if the file is INTERNAL or EXTERNAL and only depend on what system J 
file is connected to the INTERNAL or EXTERNAL PL/I file. The rules are: 


e Ifthe system file is a data base file or a named inline data file, all connections 
access the same set of records. 


e If the system file is a spooled output file, each connection generates a unique set 
of spooled output. 


e If the system file is a non-spooled device file, only one connection is allowed to 
the device at a time. In this case the records on the device are accessed directly. } 


e Ifthe system file is the unnamed inline file QINLINE, each connection accesses 
the next set of unnamed inline data records. 


Considerations for Opening a Print Stream File 
When a print file is opened, the current position is at column | of line 1 of the first 
page. If your first PUT statement specifies that a certain number of lines are 
skipped, the skip will be based on this position. For instance, SKIP (3) indicates 
that printing begins on the fourth line, because it is the third line following the first 


line on the page. ) 


Considerations for Opening a Non-Print Stream File 
When a non-print stream file is opened, the current position is before the first record 
(the current position is at the end of an imaginary record immediately preceding the 
record accessed in the first GET or PUT statement). Therefore, if the first GET or 
PUT specifies, by means of a statement option or format item, that 7 lines are to be 
skipped before the first record is accessed, the current position will be at the start of 
record 7. 


Considerations for Opening SYSPRINT 
When an action occurs that sends diagnostic output to SYSPRINT (for example, 
when you specify the GENOPT option «DIAGNOSE on the CL command 
CRTPLIPGM (Create PL/I Program)), this implicitly opens the file SYSPRINT 
with the attributes EXTERNAL, OUTPUT, STREAM, and PRINT. If you J 
attempt to open SYSPRINT after this implicit opening, the attributes and options 
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you specify will be ignored, and any resulting incompatibilities will cause errors. 
This may be avoided if you declare SYSPRINT open with the INTERNAL scope 
attribute. 


Considerations for File Closing after an Error 
When a close operation involving certain device files (for example, Bsc, Communi- 
cations and Tape) occurs due to a run time error such as an operation with invalid 
data or a device error, PL/I must inform the system of the error condition so the 
system can correctly close the file. See the Communications: Programmer's Guide 
for details on closing files during error conditions. 


PL/I will close a file with an error indication whenever a run unit ends and any of 
the following conditions are true: 


The job return code is greater than one. 

Control reaches the end of an ERROR on-unit. 

An ERROR condition is raised and no ERROR on unit exists. 
A STOP statement is processed. 


If you do not use a CLOSE statement to close a file, it is closed at the end of the 
run unit. For a complete description of implicit file closing refer to the section: 
“Scoping of Open Files (File Sharing)” on page 7-11. 


If a CLOSE statement is processed within an ERROR on unit, the error close 
system interface is used. At compile time, if a called subroutine is within the scope 
of the ON unit block, and a called subroutine closes the file, an error close will 
occur. However, calls to subroutines outside the scope of the ON unit begin block 
will not close the file in error. 


The OPTIONS Option of Record Data Transmission Statements 


The OPTIONS option enhances the function of the record input/output statements 
READ, WRITE, REWRITE, and DELETE, to allow access to specific AS/400 
data management functions. The syntax of the OPTIONS option is: 
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ai ery i 
RECORD(character_expression) 
bene EQUAL : a NEXT ‘ 


AFTER PREVIOUS 
BEFORE NXTUN 
EQLAFT PRVUN 
EQLBFR NXTEQL 
PRVEQL 
FIRST 


LAST 


 seonattenbideies inuanatel | aniieicadiaed 
Lapeeeel 


Abbreviations: EQL for EQUAL 
AFT for AFTER 
BFR for BEFORE 
NXT for NEXT 
PRV for PREVIOUS 


OPTIONS is not allowed if BLOCK is specified as an ENVIRONMENT option 
for the file. 


The parameters of the OPTIONS option may be specified in any order. 

Figure 11-1 on page 11-17 shows valid combinations of option parameters and file 
organizations. Complete rules are shown in Appendix C, “Valid Combinations of 
Options for Input/Output Statements.” The following sections describe the parame- 
ters of the OPTIONS option. 


The OPTIONS parameters are discussed in the following order: 


RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED. 
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RECORD Parameter 


RECORD may be specified for a physical, logical, display, printer, BSC, or commu- 
nications file that contains DDs record formats. It must be specified for a printer file 
with the ENVIRONMENT option DESCRIBED. It may be specified for any file 
organization for which the OPTIONS option 1s valid. 7 


The RECORD parameter identifies a specific record format defined within a file 
object. The value of the character expression is the name of the record format. 
You may use uppercase or lowercase letters, but the expression is converted to 
uppercase by the compiler. If the record format does not exist in the file to which 
the input/output statement is directed, the TRANSMIT condition is raised. 


READ Using the RECORD Parameter 


Every record in a file has a record format assigned to it. A file can have one or 
several record formats. When used with the READ statement, the RECORD 
parameter specifies the record format of the record which will be read in. 


When used with a READ statement to a logical data base file that contains more 
than one record format, the RECORD option alters the search for the next record 
on the file access path. The next record read in will have the specified format, and 
any intervening records with different formats will be bypassed. 


This is shown in Figure 7-3 fora SEQUENTIAL READ from a logical data base 
file with multiple record formats. 


Logical File Records 


RECORDA 


[/// RECORDC ///// 
RECORDA 


// RECORDB /// 
RECORDD 


// RECORDB /// 


—_————_———— Current 
file 
position 


+—_—_____————- File Position 
after processing 
READ statement 


Figure 7-3. Example of RECORD Parameter 


The logical file shown above contains four record formats, and the current file posi- 
tion is ata RECORDA. If you process the statement: 


READ /././. OPTIONS (RECORD (RECORDB)); 
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the record returned is the first record after the current file position that matches 
format B. If there are no records after the current file position that match format B, 
the ENDFILE condition is raised. 


For physical and logical data base files, when the RECORD parameter is specified 
together with the KEY option or the KEYSEARCH, POSITION, or 
NBRKEYFLDS parameters, the following occurs. For the KEY option and the 
KEYSEARCH and NBRKEYFLDS parameters, the keyed access path is searched 
for a record that satisfies the key value optionally modified by the KEYSEARCH 
and NBRKEYFLDS rules. Ifa record is found, the RECORD value is compared 
for a matching record format name. If the record found does not match the 
RECORD value, additional access path entries are examined until a matching 
RECORD is found or a KEY condition 1s raised. 


If you do not specify the RECORD parameter in a READ statement, a system- 
defined default is applied. The default values are given in the Programming: 
Control Language Programmer's Guide: they depend on the file type you are using. 
Also, the system will return the record format name of the last record read into the 
I/O feedback area. See ‘“PLITOFDB Built-In Subroutine” on page 15-16 for more 
details on how to access this information. 


WRITE Using the RECORD Parameter 


When used with the WRITE statement, the RECORD parameter specifies which 
format in the object file is used to create the new record in the file. You are respon- 
sible for ensuring that the data in the FROM option variable matches the record 
format description, because no check is made at run time. 


RECORD is required for a WRITE to a multiple format logical file unless a format 
selection program is defined. (See the FMTSLR parameter on the CL command 
CRTLF (Create Logical File) in the Programming: Control Language Reference.) 


When used with the WRITE statement to a display, printer, BSc, or communi- 
cations file, the record format name supplied in the RECORD parameter determines 
the valid indicators supplied in the INDICATORS parameter. See “INDICATORS 
Parameter” on page 7-19. 


REWRITE Using the RECORD Parameter 


The use of RECORD with REWRITE is similar to its use with WRITE. You 
must specify RECORD if you are using a subfile. WRITE is optional with data 
base files, but it can provide useful documentation if you include it in your code. If 
you use a key, RECORD qualifies the search so that only records of the specified 
format are examined. If you do not use a key, the format specified must match that 
of the last record read. As with WRITE, you must ensure that the data being 
rewritten matches the record format specified, because no check is made at run time. 
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| DELETE Using the RECORD Parameter 


The use of RECORD with DELETE is the same as for REWRITE, except that 
RECORD cannot be specified when you are deleting a subfile record. 


KEYSEARCH Parameter 
The KEYSEARCH parameter of the READ statement applies only to files with 
INDEXED organization and SEQUENTIAL KEYED or DIRECT access. It 
enhances the key searching by allowing key comparisons other than key equal. The 
comparisons (except for EQUAL) are for key values either preceding or following 
the key value supplied. For example, if the keyed access path is descending, an 
option of AFTER will locate a key value that is lower in value than the key value 
supplied. 


Cc The KEYSEARCH parameter can be used with the NBRKEYFLDS and 

RECORD parameters. If the NBRKEYFLDS parameter is used, searching is 
restricted to the key values within the NBRKEYFLDS constant specified. If the 
RECORD parameter is used, the searching is restricted to the record format speci- 
fied. 


If KEYSEARCH is not specified, EQUAL is the default. 


The KEYSEARCH values are: 


( Value Description 


EQUAL Locate the first key (searching forwards) that is equal to the key 
value supplied in the KEY(expression). 
AFTER Locate the first key (searching forwards) that is after the key value 


supplied in the KEY(expression). 


BEFORE Locate the first key (searching backwards) that is before the key 
value supplied in the KEY(expression). 


value supplied in the KEY(expression). If no equal key exists, then 
locate the first key after the key value supplied in the 
KEY(expression). 


EQLBFR Locate the first key (searching forwards) that is equal to the key 
value supplied in the KEY(expression). If no equal key exists, then 
locate the first key (searching backwards) that is before the key 
value supplied in the KEY(expression). 


( EQLAFT Locate the first key (searching forwards) that is equal to the key 


POSITION Parameter 
The POSITION parameter of the READ statement cannot be used with INTER- 
ACTIVE organization or DIRECT access. Values NXTUNQ, PRVUNQ, 
NXTEQL, and PRVEQL can be used only with INDEXED organization. POSI- 
TION cannot be specified if KEY 1s specified. If RECORD is used with the POSI- 
TION parameter, only records with matching record formats are searched. 
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For information on using the POSITION parameter to read a file for which you 
have issued a CL override command, OVRDBF specifying MBR(+ALL), see 
‘‘Members” on page 6-6. 


The POSITION values are: 


Value 
NEXT 


PREVIOUS 


NXTUNQ 


PRVUNQ 


NXTEQL 


PRVEQL 


FIRST 
LAST 


NBRKEYFLDS Parameter 


Description 


Locate the next record in the access path. NEXT is the default if 
POSITION is not specified. 


Read the previous record in the access path relative to the current 
file position. 


Locate the next record in the access path that contains a different 
key value than the key value of the current file position. A current 
file position is required. If NBRKEYFLDS is specified, only key 
values within the number of fields specified are used to locate the 
next different key value. 


Locate the nearest previous record in the access path that contains a 
different key value from the key value of the current file position. If 
NBRKEYFLDS is specified, only key values within the number of 
fields specified are used to locate the previous different key value. 


Locate the next record in the access path provided the key value of 
the next record is equal to the key value of the current file position. 
If the next record does not contain an equal key value, the KEY 
condition is raised. The test for an equal key value is made only 
within the NBRKEYFLDS specified or defaulted. 


Locate the previous record in the access path provided the key value 
of the previous record is equal to the key value of the current file 
position. If the previous record does not contain an equal key value, 
the KEY condition is raised. The test for an equal key value is 
made only within the NBRKEYFLDS specified or defaulted. 


Locate the first non-deleted record in the access path. 


Locate the last non-deleted record in the access path. 


The NBRKEYFLDS parameter of the READ statement may be used with 
INDEXED file organization. It specifies the number of key fields that are contained 
in the KEY expression. 


If you do not specify the NBRKEYFLDS option, the length of the evaluated 
expression in the KEY expression is passed to the system. If the length is in 
between key fields, the system uses this length to process a generic key search. 
Refer to the Programming: Control Language Programmer's Guide for more infor- 


mation. 
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C INDICATORS Parameter 
The INDICATORS parameter of the READ, WRITE, and REWRITE statements 
may be used with INTERACTIVE organization, or with the READ or WRITE 
statement with CONSECUTIVE organization and SEQUENTIAL access. The file 
must contain external record definitions and must have the pps INDARA keyword 
specified in order to use INDICATORS. Use of the DDs INDARA keyword is 
recommended for PL/I programs. 


INDICATORS are used to communicate additional input/output information for 
display, printer, BSC, and communications files. The variable specified is used in a 
WRITE or REWRITE statement to set option indicators and to set response indi- 
cators after a READ statement. For more information on how to use indicators, 
refer to “Indicators” on page 8-76. 


The variable specified with INDICATORS should contain one byte for each indi- 

Cc cator defined for the record format. Each indicator number (from 1 to 99) corre- 
sponds to one byte in the variable. For example, indicator | is the first byte in the 
variable, indicator 5 is the fifth byte in the variable, and so on. The variable sup- 
plied with INDICATORS should be as long as the highest indicator defined for the 
record format. You can use the %INCLUDE directive to obtain a declaration of 
valid INDICATORS for each record format (see “Using the %INCLUDE Directive 
for External File Descriptions” on page 8-73). 


On a WRITE or REWRITE statement using INDICATORS, the indicators defined 

Cc for the record format must be set to either an on response of 'F1'X or an off 
response of 'F0'X. Indicators not defined for the record format are not examined. 
On a READ statement, the indicators defined for the record format returned to the 
program will be set to either an on-response of 'F1'X or an off-response of 'FO'X. 
Indicators not defined for the record format are not modified. 


If the DDS keyword INDARA is not used in the external description of the file, but 

indicators are defined for the record, do not use the INDICATORS option to 

specify the presence of indicators. Furthermore, if the ENVIRONMENT option 

DESCRIBED is not specified, you must specify the ENVIRONMENT option 
cC NOINDARA. 


If the DDs keyword INDARA is used in the external description of the file, and if 
the ENVIRONMENT option DESCRIBED is not specified, PL/I defaults to 
assuming the DDS keyword INDARA has been specified. For a WRITE or 
REWRITE, the indicators are in the output buffer. You must include the indica- 
tors in the record variable as part of the FROM option. 


For a READ, the indicators are in the input buffer, and the INTO variable contains 
the indicators. If you use the SET option, the pointer-variable is set to the address 
of the first indicator in the input buffer. The indicators defined for the record 
format appear in the buffer in front of the data record. For examples showing the 
use of indicators, see “Example of Using Indicators” on page 8-43. 
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MODIFIED Parameter 
The MODIFIED parameter of the READ statement may be used with INTERAC- 
TIVE organization and SEQUENTIAL KEYED access. This parameter applies to 


subfile processing. If MODIFIED is specified, the record read is the next subfile 
record that has been modified. 
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Chapter 8. Using AS/400 Files 


After you have created the file and an external source file description (see the 
Programming: Control Language Reference, Programming: Data Management 
Guide, and the Programming: Data Description Specifications Reference), you must 
do the following in your program to use an AS/400 PL! file: 


1. Define the file in a DECLARE FILE statement. 

2. Optionally include the record definitions with the % INCLUDE directive. 
3. Open the file, either implicitly or explicitly. 

4. Process the input and output. 

5. Close the file, either implicitly or explicitly. 


If you wish, you can then go through steps 3, 4, and 5 again. 


Much of the information needed to carry out these operations is contained in 
Chapter 11, “Input and Output Statements,” in Chapter 6, “AS/400 PL/I File and 
Record Management” and Chapter 7, ‘File Declaration and Input/Output.” This 
chapter is concerned mainly with the relationship among all of this material. 


This chapter is arranged in a series of examples illustrating the different types of data 
base files, and how they are updated, described, read, and so on. This chapter also 
contains information on commitment control and the %INCLUDE directive. 


Using Data Base Files 


A large amount of the input and output processed on the AS/400 System involves 

data base files. One of the unique aspects of data base files is discussed in 

Chapter 6, “AS/400 PL/I File and Record Management.” The ENVIRONMENT 
options CONSECUTIVE and INDEXED, and the file attributes SEQUENTIAL, 

DIRECT, and KEYED, deal with access paths. 


The ENVIRONMENT option CONSECUTIVE specifies that the file is to be 
processed using the arrival sequence access path. If you specify SEQUENTIAL 
access, you can only process the file sequentially: no relative record number keys 
can be specified. If you specify DIRECT access, you can obtain the record with the 
relative record number specified in the KEY or KEYFROM option of the 
input/output statement. If you specify SEQUENTIAL KEYED access, you can 
process the file either sequentially or by relative record numbers. 


INDEXED specifies that the file is processed using the keyed sequence access path. 
If you specify SEQUENTIAL access, you can only process the file sequentially 
using the keyed sequence access path: you cannot specify a key. If you specify 
DIRECT access, you obtain a record with the key specified in the KEY or 
KEYFROM option of the input/output statement. If you specify SEQUENTIAL 
KEYED access, you can process the file either sequentially or by key. 
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With INDEXED organization, you also use the ENVIRONMENT attribute 
options KEYDISP and KEYLENGTH to process the key. The various 
input/output statement options you specify with each combination of file organiza- 
tion and access are shown in Appendix C, “Valid Combinations of Options for 
Input/Output Statements.” 


Also in the ENVIRONMENT option list, you have the option of specifying that 
you wish to use commitment control. You do this by declaring the 
COMMITTABLE option. Commitment control is described in “Commitment 
Control” on page 8-58. 


Other ENVIRONMENT options which can be specified with data base files are 
BLOCK, BUFSIZE, EXCL, and EXCLRD. These options are described in 
Chapter 7, “File Declaration and Input/Output.” 


Externally Described Data Base Files 
When using an externally described data base file with INDEXED organization, you 
have the option to specify the DESCRIBED option of the ENVIRONMENT attri- 
bute. This is discussed in Chapter 7, “File Declaration and Input/Output.” Level 
checking is described in Chapter 6, “AS/400 PL/I File and Record Management.” 


For logical data base files, it is possible to map one record format to more than one 
base physical file member with the DIAMBRS parameter on the CL commands 
CRTLF and ADDLFM. A WRITE statement to a format of this type will fail. 


Program-Described Data Base Files 
In a program-described data base file, the record format or formats are described in 
the program. Even if there is a record format description in the DDS, it 1s ignored. 
When you describe a file in your program, you cannot use the % INCLUDE direc- 
tive or the DESCRIBED attribute. There is no level checking when your program 
accesses the file, so you will not be protected against any changes in the record 
format made since you wrote your program. If you are using INDEXED files, you 
must specify KEYDISP and KEYLENGTH in your file declaration. 


Data Description Specifications 
For a full discussion of DDs coding and use, see the Programming: Data 
Description Specifications Reference. Examples are given here of a physical file DDs 
and a logical file Dps. The physical file, CUSMSTP, is used in the example in 
Figure 8-9 on page 8-23. 
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C Example 1 — Describing a Physical File 
TRY AS/400 DATA DESCRIPTION SPECIFICATIONS Gra -0991-0 Un/O50- 
== International Business Machines Number of sheets per pod ney ey ley, 
oe trie, Ft 
aa aR |r Ce ED OB 


Usage is /0/1/8/H/M/N/P} 


r nt 
YSICAL! USMSTP |_| 


1] Hi CUSTOMER MAS 
P= =a neo Re USMST es ti EXT (*CUSTOMER MASTER RECORD") 
: PUA OT TP eost TT tt OT TEXTE CUSTOMER 
4 a et 23 $+ Tt *CUSTOMER NAME? ; 
Ty yt Ty aApprR Tf Ty 2a LL} _TEXT( “CUSTOMER ADDRESS") 
[erry | | [| 20] [| [|  (TeExXT¢*CUSTOMER CITY’) 
POPPSTATE TO ERT STATE 
egy ooo EXT(*2ZIP CODE*) 
|| ISRHCOO! | jth, CTT CSTEXTC* CUSTOMER NUMBER SEARCH CODE‘) | 
Ht USTYPL [| [| iS aol | |TEXT(*CUSTOMER TYPE 1=66V 2=SCH + 
REO 


B22 |_| TEXT *ACCTS REC BALANCE‘ ) 
| 4] | 'TEXTt*A/R AMT IN ORDER FILE") 
| TEXT LAST AMT PAID IN A/R* 


ROTTS BAT es TETAS RTE RAT 
At _tit tt RDLMT| | [| 8S 2] | TT EXTC'GUSTOMER CREDIT LIMIT® 
Al +4 4 TEXT( *CUSTOMER SALES THIS YEAR?) 
: TEXT(*CUSTOMER SALES LAST YEAR‘) | 


c 


Figure 8-1. Physical Data Base File DDS 
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Example 2— Describing a Logical File 


AS/400 DATA DESCRIPTION SPECIFICATIONS Cae 


«Number of sheets per pod may vory alightly, 


f= LIT ae 
[Cac 


= International Business Machines 


archi 
62 42 44/48 45 47 G8 4? 2) 8) FT 8) BS 83 OS ST SE OF OS Gt G2 6) 64 0S OS C7 OY Pe vl rE 7a ee 7? ee 


USMSTL! | "CUSTOMER MASTER KEYED BY NAMES fEYED BY NAME —S 
rope rh areususy UP Pn priceccusmstey PFILEC(CUSMSTP) 
| ECU OT TE CL eust ft tt | 
AE Wane oe 


Figure 8-2. Logical Data Base File DDS 
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Example 3 - Writing Sequentially to a File with a Keyed Sequence Access Path 


SEQNBR STMT.SUBS BLK BN DO 


PL/I Source Listing PLITST/LP1413 
LP1413: PROCEDURE; 


RE Pee lia coined lies 


Figure 8-3. Program Writing to a File with a Keyed Sequence Access Path 


11/30/88 15:51:24 


RECORD data transmission is used with IN_FILE. 


Page 3 
PUBG6166 


i ee re Ee Les. ee, TORO « NE, PRM 2 Pee, mane | Date 


a LP1413: PROCEDURE; PUBGA160 830817 
200 PUBO0170 
300 /* FILE DECLARATIONS */ PUBG0180 
400 2 11 DECLARE fl 2| 3 4 PuBe8190 
500 1 1 IN_FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE  PUBQ6200 830930 
600 1 1 ; BUFSIZE(38)f 831114 
7000S 21 1 1 IND_FILE FILE RECORD INTERNAL SEQUENTIAL OUTPUT ENV( INDEXED PUB00210 
800 1 1 7 KEYDISP(6) KEYLENGTH(16)); 831114 
960 PUB90220 
1980 /* RECORD DECLARATIONS */ PUBe230 
110803 1 1 DECLARE pupe0240 
1200 1 1 1 INDEX_RECORD, PuBee250 831114 
1300 3.1 1 1 2 INDEX_KEY CHAR(16), PUB00270 
1408 3.2 1 1 2 INDEX_NAME CHAR(28), PuB06280 
1508 = 3.3 11 2 INDEX_BAL PICTURE '999999V9R', pupee298 831003 
( 1600 3.4 11 1 INPUT_RECORD, PuBe0308 
1700 03.5 1 1 2 INPUT_KEY CHAR(18) , PUB00310 
1800 = «3.6 1 1 2 INPUT_NAME CHAR(26), PUB00320 
1998 = 3.7 1 1 2 INPUT _BAL PICTURE '999999V9R'; PUB0330 831003 
2000 pup0e340 
2100 /* PROGRAM FLAGS */ puB00350 
22004 11 DECLARE PUBG0360 
2360 1 1 1 BIT_FLAGS STATIC, PUB00370 
2400 4.1 11 2 MORE_RECORDS BIT(1) ALIGNED, PUBO0380 
2500 «= 4.2 1 1 2 NO BIT(1) ALIGNED INIT('6'B), PUB06390 
2600 «= 4.3 11 2 YES BIT(1) ALIGNED INIT('1'B); pupee4ee 
2700 puse0410 
28005 1 1 ON ENDFILE(IN_FILE) PUB08428 
' 2900 1 1 MORE RECORDS = NO; pus0e430 
3000 PUB00440 
3100 /* MAIN PROGRAM */ PuB0e450 
3200 —«6 1 1 MORE_RECORDS = YES; puBe84Ge 
3300 pupee476e 
34007 1 1 OPEN PUBNe480 
3560 1 1 FILE (IN-FILE) TITLE('INFILE'); /* INPUT */ puBee49e 838919 
3600 = 8 1 1 OPEN pup0e5e0 
3700 1 1 FILE (IND_FILE) TITLE('MSTFILE'); /* OUTPUT */ PUBO0510 830929 
3800 PUB08520 
39009 1 1 READ FILE (IN_FILE) INTO (INPUT_RECORD) ; PUB00530 
4900 PUBe0540 
4160 = 10 1 1 DO WHILE (MORE_RECORDS) ; PUuBOe550 
420011 111 INDEX_RECORD = INPUT RECORD; Pup9es566 831114 
4300 = 12 111 WRITE FILE (IND FILE) FROM (INDEX_RECORD); [¥l PUB8e598 936930 
4400 = 13 111 READ FILE (1N_FILE) INTO (INPUT_RECORD) ; PUBG8600 
4560 8614 111 END; /* DO WHILE */ PUB00610 
4600 PUB08620 
4768 «= 15 1 1 CLOSE PUB00630 
4800 1 1 FILE (IN_FILE); PUBD0640 
490816 1 1 CLOSE PUB0e650 
5000 1 1 FILE (1ND_FILE); PUB08660 
5160 PUBG8670 
5200 917 11 END LP1413; puboe6se 836817 


The SEQUENTIAL access method is used with IN_FILE. Sequential reads 
and writes can be processed on any data base file if it has an arrival sequence 
access path or a keyed sequence access path. 


IN_FILE is used for INPUT only: no output is directed to it. 
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Roose 


CONSECUTIVE specifies that IN_FILE is processed using the arrival 


sequence access path. 


BUFSIZE(38) indicates that the maximum record length is 38 characters. 
When the file is opened, this is the amount of storage the program allocates 
in the buffer for a record. If your data is blocked, your program will run 
faster if you specify BLOCK instead of BUFSIZE; this is explained in note 5 
of Figure 8-4 on page 8-7. 


RECORD data transmission is used with IND_FILE. 

The SEQUENTIAL access method is used with IND_FILE. 

IND_FILE is used for OUTPUT only: it provides no data to the program. 
INDEXED specifies that IND_FILE has a keyed sequence access path. 


KEYLENGTH(10) indicates that the key field is ten characters in length and 
KEYDISP(0) indicates that there are zero characters to the start of the key 
field from the beginning of the record. Therefore, the key is the first field in 
the record. KEYDISP and KEYLENGTH must be specified here, because 
the DESCRIBED option is not specified and the compiler is not drawing 
information on the key field from the external record format definition. 


Because IND_FILE is being accessed sequentially, KEY is not specified with 
the WRITE statement, even though the file has a keyed sequence access 
path. 
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Example 4 - Updating a File with an Arrival Sequence Access Path 
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SEQNBR STMT.SUBS BLK BN DO 


PL/I Source Listing 
LP1412: PROCEDURE; 
Re. ivcclesed tines lis oat esas aeaness 
LP1412: PROCEDURE; 


PLITST/LP1412 11/36/88 14:16:40 


/* FILE DECLARATIONS */ 


DECLARE i 2] 3 4 
IN_FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE 
BLOCK) 
MST FILE FILE RECORD INTERNAL SEQUENTIAL ENV(CONSECUTIVED! 
7 BLOCK) ,fJ 
SYSPRINT FILE STREAM OUTPUT PRINT; 
/* RECORD DECLARATIONS */ 
DECLARE 


1 INPUT_EMPLOYEE, 
2 IN_EMP_NUMBER 
2 IN_EMP_NAME 


PICTURE '999999', 
CHAR(28), 


1608 
1708 
1806 


2 IN_EMP CODE 
2 IN_EMP_SALARY 
1 MASTER_EMPLOYEE, 


PICTURE '9', 
PICTURE '999999V99', 


1900 
2000 
2100 
2200 
2300 
2400 
2500 4 
2600 

2700 


2900 
3000 
3100 
3200 5 
3360 
3400 6 
3500 
3600 
3700 
3800 7 
3900 8 
4000 
4100 9 
4200 
4300 10 
4400 
4500 
4600 11 
4700 12 
4860 
4900 13 
5000 14 
5100 
5200 15 
5300 
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2 MST _EMP_NUMBER 
2 MST_ENP_NANE 
2 MST_EMP_CODE 
2 MST EMP SALARY 


PICTURE '999999', 
CHAR(28), 

PICTURE '9', 

PICTURE '999999V99"; 


/* PROGRAM FLAGS */ 
DECLARE 
1 BIT_FLAGS STATIC, 
2 MORE_RECORDS_INPUT 
2 MORE_RECORDS MASTER 
2 NO 
2 YES 


BIT(1) 
BIT(1) 
BIT(1) 
BIT(1) 


ALIGNED, 
ALIGNED, 
ALIGNED 
ALIGNED 


INIT('6'B), 
INIT('1'B); 


ON ENDFILE (IN FILE) 
MORE_RECORDS_INPUT = NO; 

ON ENOFILE (MST_FILE) 
MORE_RECORDS_MASTER = NO; 


/* MAIN PROGRAM */ 
MORE_RECORDS_INPUT = YES; 
MORE_RECORDS MASTER = YES; 


OPEN 
FILE (IN FILE) TITLE('UPDATES'); 
OPEN 
FILE (MST FILE) . TITLE('MSTFILE'); fF) 
15 
READ FILE (IN FILE) INTO (INPUT EMPLOYEE) ; 
i FILE (MST FILE) INTO (MASTER_EMPLOYEE) ; 
16 
00 WHILE (MORE_RECORDS INPUT & MORE_RECORDS MASTER); 
IF MST_EMP_NUMBER < IN_EMP_NUMBER THEN 
READ FILE (MST_FILE) INTO (MASTER_EMPLOYEE) ; 
ELSE 
IF MST_EMP_NUMBER = IN EMP_NUMBER THEN 


/* INPUT */ 


8-4 (Part | of 2). Program Updating a File with an Arrival Sequence Access Path 


Chapter 8. Using AS/400 Files 


Page 
PUB8O166 


ee Pe ees: Ra em Le ARE Smee. 


PUBO6160 


‘ PUBOO170 


PUBQG180 
PUB0G196 
PUBO0280 


PUB08210 


PUBO0220 
PUBQ0238 
PUBO0246 
PUBB0250 
PUBQ0268 
PUBOO270 
PUBG0280 
PUB08290 
PUBQ0300 
PUB60310 
PUBO0320 
PUB00330 
PUBQ0340 
PUB00350 
PUB00360 
PUB00370 
PUBO0380 
PUBGO390 
PUBQ0400 
PUBQ0410 
PUBQ0420 
PUBO0430 
PUBG0750 
PUBO0766 
PUB00770 
PUBGO780 
PUBOG790 
PUBO0800 
PUB90810 
PUBO0820 
PUB00830 
PUB00850 
PUBQ0860 
PUBQ0870 
PUB80888 
PUBO0890 
PUBO0910 
PUBG0920 
PUBO0930 
PUBQ0940 
PUB60950 
PUBG0980 
PUB@1000 
PUBO1010 


2 


Date 
830817 


830913 
831114 
831114 
831114 
830607 


830919 


830919 


8-7 


USING DATA BASE FILES 


5728PL1 RO1 M86 886715 


Include 
5400 
5508 
5660 
5760 
5868 
5960 
6066 
6100 
6260 
6360 
6400 
6560 
6600 
6760 
6866 
6908 
7008 
7160 
7260 
7300 
7408 
7508 
7600 
7700 
7806 
7906 
8606 
8100 
8200 
8300 
8400 
8560 
8600 
8700 
8800 
8900 
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PL/I Source Listing 
LP1412: PROCEDURE; 


RO Fis Lew cats dee vcwad cen biwen Pewee le wee tce se bees 


PLITST/LP1412 


1 D0; PUBO1020 
2 FE] 4 REWRITE FILE (MST_FILE) FROM (INPUT_EMPLOYEE) ; PUBO1648 
2 READ FILE (IN FILE) INTO (INPUT EMPLOYEE); PUB61060 
2 READ FILE (MST_FILE) INTO (MASTER_EMPLOYEE) ; PUBO1678 
2 END; /* DO */ PUBO1088 
1 ELSE PUB81090 
1 DO; PUBA1100 
2 FR! = PUT FILE(SYSPRINT) SKIP EDIT (‘ERROR--> INPUT RECORD ', PUBO1116 
2 IN_EMP_NUMBER, PUBO1126 
2 ' CANNOT BE FOUND IN THE MASTER FILE.') PUBO1130 
2 (A(23) ,X(2) ,F (6) .X(2) ,A(36)): PUBO1146 
2 READ FILE (IN FILE) INTO (INPUT_EMPLOYEE) ; PUB@1160 
2 END; /* DO */ PUB@1170 
1 END; /* DO WHILE */ PUB@1180 
PUBO11968 
/* APPEND ANY NEW RECORDS TO END OF MASTER FILE */ PUB@1200 
IF MORE_RECORDS INPUT THEN PUBe1216 
DO; PUBON1226 
/* CLOSE THE UPDATED MASTER FILE & REOPEN AS AN OUTPUT FILE */ = PUBO1230 
1 CLOSE PUBO1250 
1 FILE (MST_FILE); PUB 1266 
1 OPEN PUBO1280 
1 FILE (MST_FILE) OUTPUT TITLE('MSTFILE'); PUB81296 
PUB@1300 
1 DO WHILE(MORE_RECORDS_INPUT) ; PUBO1310 
2 WRITE FILE (MST_FILE) FROM (INPUT_EMPLOYEE) ; PUB01330 
2 READ FILE (IN_FILE) INTO (INPUT EMPLOYEE) ; PUB@1350 
2 END; /* DO WHILE */ PUBO1360 
1 END; /* DO */ PUBO1370 
PUBO1380 
CLOSE PUBO1400 
FILE (IN_FILE); PUBO1410 
CLOSE PUBO1420 
FILE (MST_FILE); PUBO1430 
PUB01440 

END LP1412; PUBO1450 836817 


Figure 8-4 (Part 2 of 2). Program Updating a File with an Arrival Sequence Access Path 
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The SEQUENTIAL access method is used with IN_FILE. 
IN_FILE is used for INPUT only: no output is directed to it. 


CONSECUTIVE specifies that IN_FILE is processed using the arrival 
sequence access path. 


BLOCK specifies that instead of a single record, an entire block of data is 
read into or out of the buffer. Individual records are moved between the 
buffer and the program when required. This reduces the number of 
input/output operations needed, and therefore the program will run faster. 


RECORD data transmission is used with MST_FILE. 
The SEQUENTIAL access method is used with MST_FILE. 


CONSECUTIVE specifies that MST_FILE is processed using the arrival 
sequence access path. 


BLOCK specifies that each input/output operation moves a block of data to 
or from the buffer instead of a single record. 
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STREAM data transmission is used with SYSPRINT. Stream files can only 


be accessed sequentially. 
SYSPRINT receives OUTPUT only. It provides no data to the program. 


The PRINT attribute indicates that the first character in the record 1s an 
ASA printer control character. 


IN_FILE is opened with the TITLE option specifying 'UPDATES'. 
Because the library and member names are allowed to default, the first 
member of file UPDATES in the library list is opened. 


MST_FILE is opened with the TITLE option specifying 'MSTFILE'. 
Because the library and member names are allowed to default, the first 
member of file MSTFILE in the library list is opened. 


The UPDATE attribute is specified for MST_FILE. There is no similar 
option specified for IN_ FILE, because INPUT has already been specified as 
its data transmission mode in the file declaration. You can specify the data 
transmission mode for a file either in the file declaration or in the OPEN 
statement. If you specify the data transmission mode in both places, you 
must be sure that the mode specified is the same in both places. If you 
specify the mode in the OPEN statement only, you can close the file and 
then reopen it specifying a different data transmission mode. 


You must process a READ on a non-keyed sequential UPDATE file before 
processing a REWRITE. 


The REWRITE updates the record that was read at 


SYSPRINT is implicitly opened by the PUT statement, because no OPEN 
statement is coded for it. Any file not already opened explicitly is implicitly 
opened by the first data transmission statement which accesses it. It isa 
good practice, however, to explicitly open all your files. 
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Example 5— Updating a File with a Keyed Access Path 
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PL/I Source Listing PLITST/LP1414 11/36/88 14:18:11 Page 
LP1414: PROCEDURE; PUBO8160 
Peat usre Lanse tes ive eenate catdesiet seis lees teas Suse e trae Orane tence s Pea tiaegd 
LP1414: PROCEDURE; PUBeO160 
Pus6801708 
/* FILE DECLARATIONS */ PUBOG186 
DECLARE il 2 3 pupoo190 
IN FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE PUBOE200 
: BUFSIZE(38)) 
MST FILE FILE RECORD INTERNAL DIRECT UPDATE ENV (INDEXEDG) PuBoo218 
7 KEYDISP(6) KEYLENGTH(10)), 

SYSPRINT FILE STREAM OUTPUT PRINT; 10) 
puBe9220 
/* RECORD DECLARATIONS */ puse0230 
DECLARE Pupee240 
1 MASTER_RECORD STATIC, PuB90256 
2 MASTER_KEY, PuB00278 
3 MASTER_GEN FLD CHAR(5), Pusee2sa 
3 MASTER_DET_FLD CHAR(5), PuBad29a 
2 MASTER_NAME CHAR(26), PUB0a300 
2 MASTER_BAL PICTURE '999999V9R', PUBO0310 
1 INPUT RECORD, PUBO0326 
2 INPUT_KEY, PUBA0330 
3  INPUT_GEN_FLD CHAR(5), PUB00340 
3 INPUT_DET_FLD CHAR(5), PUB00356 
2  INPUT_NAME CHAR(26), PUBO0360 
2 INPUT_AMT PICTURE 'S99999V99'; PUBO0370 
PUB00380 
/* PROGRAM FLAGS */ PUBQ0390 
DECLARE PuBo0400 
1 BIT_FLAGS STATIC, PUBOG410 
2 MORE_RECORDS BIT(1) ALIGNED, PuBOe420 
2 NO BIT(1) ALIGNED INIT('@'B), PUBN0430 
2 YES BIT(1) ALIGNED INIT('1'B); Pusoe44e 
PUBOO450 
/* PROGRAM VARIABLES */ PUBOG460 
DECLARE PuBQ0470 
OLD_MASTER_BAL PICTURE 'S99999V99', PyB00480 
PAGE_NUMBER BINARY FIXED(2); PuBoe490 
PUB0500 
ON ENDFILE(IN_FILE) PuB00510 
MORE_RECORDS = NO; PuBa0520 
PUBQ0530 
ON ENDPAGE (SYSPRINT) Pupoe546 
BEGIN; PUBO550 
BY] PUT FILE (SYSPRINT) PAGE EDIT(‘PAGE ',PAGE_NUMBER) PUB00560 
(X(81) ,A(6) ,F(2)); PUBOO570 
PUT FILE (SYSPRINT) SKIP(3) EDIT(*UPDATE REPORT')(X(38),A(13)); PUBOO580 
PUT FILE (SYSPRINT) SKIP(2) EDIT('KEY ID','NAME','CUR BALANCE’, PUBO0590 
"UPDATE AMOUNT’, 'NEW BALANCE’) (A(6),X(9),A(4),X(21),A(11),  PUBGO600 
X(6),A(13) .X(4) ,A(11)); PUBG0610 
PAGE_NUMBER = PAGE_NUMBER + 1; PUB0a620 
END; /* BEGIN */ PUBON0630 
PuB00640 
/* MAIN PROGRAM */ PUBQ0650 
PAGE_NUMBER = 1; PUBO0660 
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830919 
831114 
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831003 
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PL/I Source Listing PLITST/LP1414 11/36/88 14:18:11 Page 


LP1414; PROCEDURE; 


PUBGG168 


Include SEQNBR STMT.SUBS BLK BN DO 9 ®<..#..e.LecsetecesQeccateccedeccctecsAeccatececDeccctac scene ctecceDereeteee 8 
5400 «14 11 MORE_RECORDS = YES; PUB00670 
5500 PUBG0680 
5608 = 15 11 OPEN ff PuBOe690 
5700 1 1 FILE (IN-FILE) TITLE(*UPDATES'); /* INPUT */ PuB00700 
5800 «= 16 11 open FG PUBG8719 
5900 11 FILE (MST_FILE) TITLE('MSTFILE'); /* UPDATE */ PUBO00720 
6000 PUB00730 
6100 «17 1 1 SIGNAL ENDPAGE (SYSPRINT) ; PUB00740 
6200 18 1 1 READ FILE (IN_FILE) INTO (INPUT RECORD); PUBO0750 
6300 PUBO0760 
6400 = 19 11 DO WHILE (MORE_RECORDS) ; PUB00770 
6500 20 111 IF INPUT DET FLD = ' ' THEN PUBO0780 
6600 111 CALL INITSEQ; PUBO0790 
6700 21 111 ELSE PUBO0860 
6800 ae Dae CALL DYNAMIC; PUBO0810 
6900 22 111 READ FILE (IN FILE) INTO (INPUT RECORD) ; PUBO0820 
7000 «= -23 111 END; /* DO WHILE */ PUB00830 
7100 PUBG0840 
7200 89-24 11 CLOSE PUBGO850 
7300 11 FILE (IN FILE); PUBO0860 
7400025 1 1 CLOSE PUBQ0870 
7500 1 1 FILE (MST FILE); PUBO0880 
7600 PUBO0890 
7700 «26 11 INITSEQ: PROCEDURE; PUB06900 
7800 «= 27 4 2 MASTER_GEN FLD = INPUT _GEN FLD; PUB00910 
7900 = -.28 4 2 FE] «READ FILE (NST_FILE) INTO (MASTER RECORD) KEY(MASTER_KEY) Pupae920 
3000 4 2 OPTIONS(KEYSEARCH(EQLAFT) NBRKEYFLDS(1)); PUBG0930 
3190.29 4 2 DO WHILE(INPUT_GEN FLD = MASTER GEN FLD); PuB0e948 
8200 30 421 CALL SEQPROC; PUB00950 
8300 31 4 21 END; /* DO WHILE */ PUB00960 
8400 32 4 2 RETURN; PUBG0970 
8500 = 33 4 2 END INITSEQ; PUBO0980 
8600 PUB90990 
8700 © 34 11 SEQPROC: PROCEDURE; PUBO1000 
3860 635 5 2 PUT FILE (SYSPRINT) SKIP EDIT(MASTER_KEY,MASTER_NAME, PUBO1040 
8900 5 2 MASTER_BAL) (A(5) ,A(5) ,X(5) ,A(20) .X(6) ,F(10,2)); PUBO1050 
9000 36 5 2 FE = READ FILE (MST_FILE) INTO (MASTER_RECORD) KEY(MASTER KEY) PUBO1010 
9100 5 2 OPTIONS (KEYSEARCH(AFTER)) ; PuBo1020 
9200 37 5 2 RETURN; PUBO1060 
9300 38 5 2 END SEQPROC; PUBO1070 
9400 PUBO1086 
9500 39 11 DYNAMIC: PROCEDURE; PUB01096 
9600 40 6 2 MASTER_KEY = INPUT_KEY; PUBO1100 
9700 41 6 2 READ FILE (MST_FILE) INTO (MASTER_RECORD) KEY(MASTER_KEY) PUBO1110 
9800 6 2 OPTIONS (KEYSEARCH(EQUAL) ); 

9900 42 6 2 IF INPUT GEN FLD = MASTER_GEN FLD THEN PUBO1120 
10000 6 2 DO; PUBO1130 
10100 © 43 621 OLD_MASTER_BAL = MASTER BAL; PUBO1140 
19200 «44 621 MASTER_BAL = MASTER_BAL + INPUT ANT; PUBO1150 
10300 45 621 PUT FILE (SYSPRINT) SKIP EDIT(MASTER_KEY,MASTER_NAME, PUBO1160 
10490 621 OLD_MASTER_BAL, INPUT_AMT,MASTER_BAL) (A(5),A(5),X(5),A(20), PUBO1170 
10509 621 X(6),F(10,2),X(6),F(10,2),X(8),F(10,2)); PUBO1189 
10600 46 621 REWRITE FILE (MST_FILE) FROM (MASTER_RECORD) KEY(MASTER_KEY); PUBO1190 
10780 = 47 621 END; /* DO */ PUBO1200 
10800 © 48 6 2 RETURN; PUBO1210 
1e990 49 6 2 END DYNAMIC; PUBO1220 
11900 PUB01236 
11100 = 50 1 3 END LP1414; PUBO1240 
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RECORD data transmission 1s used with IN_ FILE. 
The SEQUENTIAL access method is used with IN_FILE. 
IN_FILE is used for INPUT only: no output is directed to it. 
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CONSECUTIVE specifies that IN_FILE is processed using the arrival 
sequence access path. 


BUFSIZE(38) indicates that the maximum record length is 38 characters. 
When the file is opened this is the amount of storage the program allocates in 
the buffer for a record. If your data is blocked, the program will run faster if 
you specify BLOCK instead of BUFSIZE; this is explained in note 5 of 
Figure 8-4 on page 8-7. 


RECORD data transmission is used with MST_FILE. 


The DIRECT access method is used with MST_FILE. MST_FILE is 
accessed non-sequentially. The target record is located by a key. 


MST_FILE has the UPDATE attribute, because the program will receive 
data from it and also direct data to it. 


INDEXED specifies that MST_FILE is processed using the keyed sequence 
access path. 


KEYLENGTH(10) indicates that the key field 1s ten characters in length and 
KEYDISP(0) indicates that there are no characters between the start of the 
key field and the beginning of the record. Therefore, the key is the first field 
in the record. KEYDISP and KEYLENGTH must be specified here, 
because the DESCRIBED option is not specified and the compiler is not 
drawing information on the key field from the external record format defi- 
nition. 

STREAM data transmission is used with SYSPRINT. SYSPRINT 1s 
accessed sequentially, but this is not coded as an attribute because stream 
data transmission can only use sequential access. 


SYSPRINT is used for OUTPUT only. It provides no input to the 
program. 


The PRINT attribute specifies that the first character in every record is an 
ASA printer control character. 


SYSPRINT 1s not explicitly opened by an OPEN statement; it is therefore 
implicitly opened the first tume the PUT statement is processed. Any file 
which has not been explicitly opened is implicitly opened by the first data 
transmission statement which accesses it. It is a good practice, however, to 
explicitly open all your files. 


SYSPRINT is the default file in STREAM OUTPUT files. The PUT state- 


ment will therefore compile and process correctly if FILE (SYSPRINT) is 
omitted. 


IN_FILE is opened with the TITLE option specifying 'UPDATES'; 
because the library and member names are allowed to default, the first 
member of file UPDATES in the library list is opened. 


MST _FILE is opened with the TITLE option specifying 'MSTFILE'; 
because the library and member names are allowed to default, the first 
member of file MSTFILE in the library list is opened. 
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The READ statement uses MASTER_KEY to find a record in MST_FILE 
and read it into MASTER_RECORD. The KEYSEARCH option specifies 
EQLAFT. Ifa record with a precisely equal key is not found, the record 
with the next highest key is read into MASTER_RECORD. The 
NBRKEYFLDS option is specified and given a parameter value of 1, indi- 
cating that only one key is used in the search for the record. 


The next record is read in from MASTER_FILE, using MASTER_KEY. 
KEYSEARCH(AFTER) specifies that the record with the next highest key 
after the current record is read in. 


The record read in from MST_FILE is rewritten, using MASTER_KEY. 
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LP1415: PROCEDURE; PUB80168 


Include SEQNBR STMT. SUBS BLK BN DO a a ee ee ee Aer Re err, een Cer eee. eee, aes en eee > Tem mere Date 


1060S LP1415: PROCEDURE; PUBO0160 830817 
200 PUBO0178 
300 /* FILE DECLARATIONS */ PuB00180 
4002 11 DECLARE Al 2 3] PuB00190 
500 11 IN_FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE — PUBOO2e0 831604 
600 11 BUFSIZE(23)) 8 831804 
7000 2,1 ae REL_FILE FILE RECORD INTERNAL DIRECT OUTPUT ENV(CONSECUTIVE) ; puBe0210 
800 7 G puBee220 
900 /* RECORD DECLARATIONS */ PUBQ0230 
10003 11 DECLARE PuBe0240 
1100 11 1 RELATIVE_RECORD 01, Pugo0250 
1200028 3.1 11 2 RELATIVE_RECORD(5), PuBo0260 
1300 3.2 11 3 REL_YEAR PICTURE '99', PuB0027@ 831114 
1400 2S 3..3 11 3 REL_WEEK PICTURE '99', PUB00280 831114 
1500 = 3.4 11 3 REL_UNIT_SALES PICTURE ‘$999999', PUBQ0296 
1600 = 3.5 1 1 3 REL_DOLLAR_SALES — PICTURE '$999999999V99", PUB00300 
1700 3.6 11 1 INPUT_RECORD, PUBO0310 
1800 (3.7 11 2 INPUT_YEAR PICTURE '99', PUB00320 831114 
1900 = 3.8 11 2 INPUT WEEK PICTURE '99", PUB90330 831114 
2000 «©=s-3.9 14 2 INPUT_UNIT_SALES PICTURE '$999999', PUB00340 
210023. 11 2 INPUT DOLLAR_SALES PICTURE '$999999999V99'; PUBG0356 
2200 PUB00360 
2300 /* PROGRAM FLAGS */ PUB00370 
24004 11 DECLARE PUB00380 
2500 ae 1 BIT_FLAGS STATIC, PUB00390 
260041 p 4 2 MORE_RECORDS BIT(1) ALIGNED, PuBeed0e 
2700 «4.2 Li 2 NO BIT(1) ALIGNED INIT('0'B), PUBO0410 
2800 4.3 1 1 2 YES BIT(1) ALIGNED INIT(‘1'B); PUB00420 
2900 PUB00430 
3000 /* PROGRAM VARIABLES */ PUBG0440 
3100 = 5 11 DECLARE PUB00456 
3200 11 REL_INDEX BINARY FIXED(2); PUB0G460 
3300 PUBG470 
3400 6 11 ON ENDFILE(IN_FILE) PUBGG480 
3500 1 1 MORE_RECORDS = NO; PuB00490 
3600 PUB00500 
3700 /* MAIN PROGRAM */ PUBO0516 
38007 11 MORE_RECORDS = YES; PUBO0520 
3900 = 88 bed REL_INDEX = 1; PUBO0530 
4000 PUB00540 
4100 9 11 OPEN | PUBO055a 
4200 11 FILE (IN_FILE) TITLE(‘INFILE'); /* INPUT */ PUB00560 830919 
4300 =: 10 1 1 OPEN FRI PUB9@570 
4400 1 4 FILE (REL_FILE) TITLE(*MSTFILE'); /* OUTPUT */ PUBO0580 831003 
4500 PUBO0590 
4600 = Al 7 READ FILE (IN_FILE) INTO (INPUT RECORD); PUB0OG00 
4700 PUBO0610 
4g60 «12 11 DO WHILE (MORE RECORDS); PUB00620 
490013 ie ans RELATIVE_RECORD(REL_INDEX) = INPUT_RECORD; PUB00630 
5000 «014 111 IF REL_INDEX -= 5 THEN PUBOO640 
5100 1 A, 4 REL_INDEX = REL_INDEX + 1; PuB0065e 
5200 «= «15 111 ELSE PUBDO660 
5300 111 Do; PUB00670 


Figure 8-6 (Part 1 of 2). Program Writing to an Arrival Sequence File by RRN 


8-14 PL/I User’s Guide and Reference 


C 5728PL1 RO1 M86 888715 


USING DATA BASE FILES 


PL/I Source Listing PLITST/LP1415 11/30/88 14:18:54 Page 3 

LP1415: PROCEDURE; PUBQ0160 
Include SEQNBR STMT.SUBS BLK BN 00 REF occ bie ss Peeeslovtetee se deceetses Meese teva sdeee shes WBecceteces som eateca 8. Date 

5400 16 112 REL_INDEX = 1; PUBO0680 
5500 17 1 1 2 12 WRITE FILE (REL_FILE) FROM (RELATIVE_RECORD_ 01) PUB00690 
5600 1 3-2 KEYFROM (INPUT WEEK); PUBO0700 
5700 18 112 END; /* DO */ PUBG0710 
5800 19 1-11 READ FILE (IN_FILE) INTO (INPUT RECORD) ; PUB00720 
5900 20 toi 1 END; /* DO WHILE */ PUBQ6730 
6600 PUBOQG740 
6108 21 11 CLOSE PUBO0750 
6280 11 FILE (IN FILE); PUB00760 
6300 22 1 1 CLOSE PUB00770 
6480 1 1 FILE (REL_FILE); PUB90780 
6500 PUBO0790 

6608 23 1 1 END LP1415; PUBOO800 830817 


Figure 8-6 (Part 2 of 2). Program Writing to an Arrival Sequence File by RRN 
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RECORD data transmission is used with IN_FILE. 
The SEQUENTIAL access method is used with IN_FILE. 
IN_FILE is used for INPUT only; no output is directed to it. 


The CONSECUTIVE option specifies that the file is processed using the 
arrival sequence access path. Because CONSECUTIVE is the default, it 
could have been omitted. 


BUFSIZE(23) indicates that the maximum record length is 23 characters. 
When the file is opened, this is the amount of storage the program allocates 
in the buffer for a record. If your data is blocked, your program will run 
faster if you specify BLOCK instead of BUFSIZE; this is explained in 
Figure 8-4 on page 8-7. 


RECORD data transmission is used with REL_FILE. 


The DIRECT attribute indicates that REL FILE is accessed non- 
sequentially. 


REL_FILE is used for OUTPUT only. It does not provide data for the 
program. 


The CONSECUTIVE option specifies that REL FILE has an arrival 
sequence access path. Because CONSECUTIVE is the default, the ENVI- 
RONMENT attribute can be omitted. 


The combination of the DIRECT attribute and the CONSECUTIVE option 
of the ENVIRONMENT attribute indicates that the file is accessed non- 
sequentially, without using a key field in the record. The record is found by 
using the relative record number, which indicates how far the record is from 
the start of the file. 


This program does not create an RRN-type file. The file must be created 
first, by creating a data base file with an arrival sequence access path and 
placing empty records in the file. The number of empty records placed in the 
file must be greater than or equal to the highest RRN which will later be 
used to access the file. 
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IN_FILE is opened with the TITLE option specifying 'INFILE'. Because 
the library and member names are allowed to default, the first member of file 
IN_FILE in the library list is opened. 


REL FILE is opened with the TITLE option specifying 'MSTFILE'. 
Because the library and member names are allowed to default, the first 
member of file MSTFILE in the library list is opened. 


RELATIVE RECORD 01 is written to REL_FILE using INPUT_WEEK 
as the relative record number. Because RELATIVE RECORD. 01 is an 
array which is filled by five readings of INPUT_RECORD, the assumption is 
made that INPUT_WEEK in every fifth INPUT_RECORD 1s the same as 
in the four preceding records, but that each of these five records has a dif- 
ferent INPUT_YEAR. 
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Example 7 - Updating an Arrival Sequence File by Relative Record Number 
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Include 


SEQNBR STMT.SUBS BLK BN DO 
160 1 
200 
300 
400 2 
500 
600 
700 
800 
900 

1606 
1108 
1200 
1300 
1406 
1500 
1606 
1700 
1806 
1900 
2000 
2106 
2200 
2300 
2400 4 
2500 

2600 4. 
2700 4 

2800 

2900 

3000 5 

3100 

3200 5 

3300 5. 

3400 5 

3500 

3600 6 1 1 

3700 1 1 

3800 

3900 7 1 1 

4000 1 1 

4100 

4200 

4300 8 1 1 

4400 9 1 1 

4500 

4600 10 

4700 

4800 11 

4900 

5000 

5100 12 1 1 

5200 13 1 1 

5300 
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1 INPUT_RECORD, 

2 INPUT_YEAR 

2 INPUT WEEK 

2  INPUT_UNIT SALES 

2 INPUT _DOLLAR_SALES 
1 WORK_RECORD, 

2 OLDEST_WEEK 

2 CURRENT WORK_YEARS 


/* PROGRAM VARIABLES */ 
DECLARE 

INPUT_RECORD_B 

Pl 

ADDR 


/* PROGRAM FLAGS */ 
DECLARE 


1 BIT_FLAGS STATIC, 
2 MORE_RECORDS 
2 NO 
2 YES 


ON ENDFILE(IN_FILE) 
MORE_RECORDS = NO; 


ON ENDFILE(REL_FILE) 
MORE_RECORDS = NO; 


/* MAIN PROGRAM */ 
MORE_RECORDS = YES; 
P1 = ADDR(INPUT_RECORD) ; 


EB OOPEN 
FILE (IN_FILE) 
FR) open 


TITLE('UPDATES'); 


PICTURE '99', 

PICTURE '99', 

PICTURE 'S999999', 
PICTURE '$999999999V99', 


CHAR(23), 
CHAR(92); 


CHAR(23) BASED (P1), 
POINTER, 
BUILTIN; 


BIT(1) ALIGNED, 
BIT(1) ALIGNED 
BIT(1) ALIGNED 


/* INPUT */ 


FILE (REL_FILE) TITLE('MSTFILE'); /* UPDATE */ 


FEL READ FILE (IN_FILE) 


INTO (INPUT_RECORD) ; 


INIT(‘O'B), 
INIT(*1'B); 


READ FILE (REL_FILE) INTO (WORK_RECORD) KEY (INPUT_WEEK); 


Figure 8-7 (Part 1 of 2). Program Updating an Arrival Sequence File by RRN 
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PL/I Source Listing PLITST/LP1416 11/30/88 14:26:10 Page 2 
LP1416: PROCEDURE; PUBG8168 
We ties livastitwse ecw teaawd winged valet ties Drees thas Ore teea rec tees. 8 Date 
LP1416: PROCEDURE; PuBGe16@ 830817 
PuBee170 
/* FILE DECLARATIONS */ pugee18e 
DECLARE A 3 PUB00190 
IN_FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE — PUBO@200 831004 
BUFSIZE(23)) fj 831004 
REL_FILE FILE RECORD INTERNAL DIRECT UPDATE ENV(CONSECUTIVE) ; PuBee210 
5 7 E PUB00220 
/* RECORD DECLARATIONS */ PuBee230 
DECLARE PuBed246 
1 RELATIVE_RECORD 01, pugee25e 
2 PREVIOUS WORK_YEARS CHAR(92), PUB0G260 831604 
2 LATEST_WORK_YEAR CHAR(23), PUBQG27@ 831004 


PUB88280 
PUBO8296 831114 
PUB60308 831114 
PUB00316 
PUB6G328 
PUB96336 
PUB60348 831604 
PUBQ0356 831004 
PUBQ0360 
PUB00370 
PUBO0380 
PUB88390 831604 
PUB00400 
PUBO0410 
PUBO0420 
PUB@0430 
PUB00446 
PUBOQ0450 
PUBO0460 
PUB80470 
PUBO0480 
PUB00490 
PUBQ0500 
PUB80510 
PUB00526 
PUBO0530 
PUB60540 
PUBGO558 
PUBO0566 
PUB00570 
PUBO0580 
PUBO0590 
PUBG0606 
PUB00610 831664 
PUBQ0628 
PUBQ0630 831664 
PUBO0648 
PUBO0656 
PUB80660 
PUB00670 
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Include 
5400 
5500 
5600 
5708 
5800 
5900 
6600 
6100 
6200 
6368 
6406 
6500 
6600 
6700 


14 
15 
16 
17 
18 
19 
20 


21 


22 


23 


1 


en ee ee 


a oe eo) 


1 


SEQNBR STMT.SUBS BLK BN D0 


1 


a ee oe oo od 


PL/I Source Listing 
LP1416: PROCEDURE; 
Te Pance Laslett eee Beta tsa e Oo aewtt abel ecGs tees eis et iane Om 
DO WHILE (MORE_RECORDS) ; 


PLITST/LP1416 11/30/88 14:26:16 Page 3 
PUBG0168 


oeteccesomeetee. 8 Date 


PUBGO688 

1 PREVIOUS WORK_YEARS = CURRENT WORK_YEARS; PUBBG698 
1 LATEST_WORK_YEAR = INPUT_RECORD_B; PuBee70e 
1 9H REWRITE FILE (REL_FILE) FROM (RELATIVE RECORD 01) KEY (INPUT WEEK) ;PUBO0710 
1 READ FILE (IN FILE) INTO (INPUT RECORD); PUB88720 
1 READ FILE (REL_FILE) INTO (WORK RECORD) KEY (INPUT WEEK); PUBO0730 
1 END; /* DO WHILE */ PuBG0740 
PUBGe750 

CLOSE PUBGG760 

FILE (IN FILE); PUBG0770 

CLOSE PUBGG780 

FILE (REL_FILE); pPuBea790 

puBaesee 


END LP1416; PUBOO818 830817 


Figure 8-7 (Part 2 of 2). Program Updating an Arrival Sequence File by RRN 
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RECORD data transmission is used with IN_FILE. 


The SEQUENTIAL access method 1s used with IN_FILE. IN_FILE is used 
for INPUT only; no data is directed to it. 


The CONSECUTIVE option specifies that the file is processed using the 
arrival sequence access path. Because CONSECUTIVE is the default, it 
could have been omitted. 


BUFSIZE(23) indicates that the maximum record length is 23 characters. 
When the file is opened, this is the amount of storage the program allocates 
in the buffer for a record. If your data is blocked, your program will run 
faster if you specify BLOCK instead of BUFSIZE. This is explained at 
Figure 8-4 on page 8-7. 


RECORD data transmission is used with REL _ FILE. 


REL FILE is declared with the DIRECT attribute, because it will be 
accessed non-sequentially. 


REL _FILE is declared with the UPDATE attribute, because records in the 
file are being read, altered, and then rewritten. In Figure 8-6 on page 8-14, 
the file was declared with the OUTPUT attribute because it was being loaded 
with initial data. 


The CONSECUTIVE option indicates that REL_FILE is processed using 
the arrival sequence access path. Although REL FILE does not have a 
keyed sequence access path, it can be accessed sequentially by the relative 
record number. 


IN_FILE is opened, with the TITLE option specifying 'UPDATES'. Since 
the library and member names are allowed to default, the first member of file 
UPDATES in the library list is opened. 


REL FILE is opened, with the TITLE option specifying 'MSTFILE' 
Because the library and member names are allowed to default, the first 
member of file MSTFILE in the library list is opened. 
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A record is read in from IN_FILE. A key INPUT_WEEK is obtained from 
this record and is used as the relative record number to obtain the corre- 
sponding record from REL _FILE. 


After the record from REL_FILE has been altered to incorporate the new 
information for IN_FILE, it is rewritten using the same key with which it 
was read. The record’s position in REL_FILE will stay the same. 
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Include 
166 
200 
306 
400 
500 
606 
700 
800 
900 

1800 
1166 
1200 
1300 
1400 
1506 
1600 
1700 
1866 
1900 
2000 
2100 
2200 
2308 
2400 
2506 
2600 
2708 
2800 
2900 
3000 
3100 
3200 
3300 
3400 
3500 
3600 
3700 
3800 
3900 
4000 
4100 
4200 
4300 
4400 
4500 
4600 
4700 
4800 
4900 
5000 
5108 
5200 
5300 
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Example 8 - Reading from an Arrival Sequence File by Relative Record Number 
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SEQNBR STMT.SUBS BLK BN DO 
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PL/I Source Listing PLITST/LP1417 11/36/88 14:21:28 Page 2 
LP1417: PROCEDURE; PUBEe160 
RE Hecsedeccctocecloccetesccdecsetess cds scstecccdocsctececDeccateccstarmeeteee od Date 
LP1417: PROCEDURE; PUB60168 830817 
PUBGG170 
/* FILE DECLARATIONS */ PUBGe186 
DECLARE A 3 4 PUuBee190 
IN_FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE  PUBO6266 831004 
7 BUFSIZE(4)). ff 831004 
REL_FILE FILE RECORD INTERNAL DIRECT INPUT ENV(CONSECUTIVE), PUBE8216 831004 
SYSPRINT FILE STREAM OUTPUT PRINT; 830607 
PuB0e220 
/* RECORD DECLARATIONS */ PUBGO230 
DECLARE puBe0240 
1 RELATIVE_RECORD_ 61, PUBO0250 
2 RELATIVE_RECORD(5), PUBBE260 
3 REL_YEAR PICTURE '99', PuB08270 831114 
3 REL_WEEK PICTURE ‘99', PUBee288 831114 
3 REL_UNIT SALES PICTURE '$999999', PUBGe290 
3 REL_DOLLAR_SALES PICTURE 'S999999999V99", PuB|e8300 
1 INPUT_RECORD, PUB06310 
2 INPUT_WEEK PICTURE '99', PuBO320 831114 
2 END_WEEK PICTURE '99'; PUB06330 831114 
PUBG340 
/* PROGRAM FLAGS */ PUBOE356 
DECLARE PUB06366 
1 BIT_FLAGS STATIC, PUB00370 
2 MORE_RECORDS BIT(1) ALIGNED, PUB00380 
2 NO BIT(1) ALIGNED INIT(‘@'B), PuB00390 
2 YES BIT(1) ALIGNED INIT('1'B); PuBeo400 
Pupeo410 
/* PROGRAM VARIABLES */ PuB90420 
DECLARE PUB00430 
SEQ_INCR BINARY FIXED(2), Pupoe440 
REL_INDEX BINARY FIXED(2); PUBO0450 
PUuB00460 
ON ENDFILE(IN FILE) PUBO0470 
MORE_RECORDS = NO; PUBO0486 
pPuB00490 
ON KEY(REL_FILE) PUBO8500 
BEGIN; PuBee510 
ON ERROR SYSTEM; PUB9O520 
REL_WEEK(1) = 53; PUBGG530 831114 
END; /* BEGIN */ pupees4e 
PUBGO55¢e 
/* MAIN PROGRAM */ PUBOO560 
MORE_RECORDS = YES; PUB00570 
PUB00580 
FE) open PUB0590 
FILE (INFILE) TITLE(*RETRIEVE'); /* INPUT */ PUBON6e8 831004 
RE] OPEN PUBQ0610 
FILE (REL_FILE) TITLE(’MSTFILE'); /* INPUT */ PuBee620 831604 
PUBO0630 
READ FILE (IN_FILE) INTO (INPUT_RECORD) ; PuB00640 
PUBO0650 
DO WHILE (MORE_RECORDS); PUBOO660 


Figure 8-8 (Part 1 of 2). Program Reading from an Arrival Sequence File by RRN 
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Include 
5460 
5500 
5660 
5700 
5800 
5900 
6000 
6100 
6200 
6300 
6400 
6500 
6606 
6760 
6896 
6900 
7600 
7108 
7200 
7300 
7460 
75008 
7600 
7700 
7806 
7906 
8000 
8186 
8266 
8300 
8400 
8500 
8660 
8706 
8800 
8900 
9000 
9108 
9260 
93606 
9406 
9500 
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SEQNBR STMT.SUBS BLK BN DO 
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PLITST/LP1417 11/30/88 14:21:28 
LP1417: PROCEDURE; 


a, nr ae ar, ey ee rere ee ee . Sas 


Page 
PUB60169 


3 


ey ee Pe «| Date 


1 IF END_WEEK = 66 THEN PUB80670 831114 
1 CALL RANDOM: PuBG068e 
1 ELSE PUBNO690 
1 CALL SEQUENT; PUBOO700 
1 READ FILE (IN FILE) INTO (INPUT RECORD); PUBA710 
1 END; /* DO WHILE */ PUBAO720 
PUB@0730 
CLOSE PUBO0740 
FILE (IN_FILE); PUBQO758 
CLOSE PUBO0766 
FILE (REL_FILE); PUBO6776 
PUBO8780 
RANDOM: PROCEDURE; PUBOG796 
FR} READ FILE (REL_FILE) INTO (RELATIVE_RECORD 61) KEY (INPUT WEEK);  PUBQO8G0 
IF REL_WEEK(1) == 53 THEN PUBOO81e 831114 
DO REL_INDEX = 1 TO 5; PUBO0826 
1 CALL PRT_SMY; PUBG0830 
1 END; /* DO LOOP */ PUBGO846 
END RANDOM; PUBa0856 
PUBGO86O 
SEQUENT: PROCEDURE; PUBOO876 
SEQ_INCR = 1; PUBOO880 
FE) READ FILE (REL_FILE) INTO (RELATIVE_RECORD_61) KEY (INPUT_WEEK);  PUBO@896 
IF REL_WEEK(1) -= 53 THEN PUBOO900 831114 
DO WHILE(REL_WEEK(1) <= END WEEK); PUB08910 
1 DO REL_INDEX = 1 TO 5; PuBee920 
2 CALL PRT_SMY; PUBG0930 
2 END; /* DO LooP */ Pup0e94e 
1 17] READ FILE (REL_FILE) INTO (RELATIVE _RECORD_01) PUB08950 
1 KEY (INPUT_WEEK + SEQ_INCR); PUB0E968 831114 
1 SEQ_INCR = SEQ_INCR + 1; PUBGO970 
1 END; /* DO WHILE */ PUBGO980 
END SEQUENT; PUBO8990 
PUBA1600 
PRT_SMY: PROCEDURE; PUBO1010 
RE) PUT FILE (SYSPRINT) SKIP(2) EDIT(REL_YEAR(REL_INDEX), PUBG1026 
REL_WEEK(REL_INDEX) ,REL_UNIT_SALES(REL_INDEX), PUBO1030 
REL_DOLLAR_SALES(REL_INDEX)) (A(2) ,X(5) ,A(2),X(5), PuBd1e40 831004 
F(8),X(5),F(14,2)); PUBO1050 831004 
END PRT_SMY; PUBO1060 
PUBO1070 


END LP1417; PUB01080 830817 


Figure 8-8 (Part 2 of 2). Program Reading from an Arrival Sequence File by RRN 


RECORD data transmission is used with IN_FILE. 
The SEQUENTIAL access method is used with IN_FILE. 
IN_FILE is used for INPUT only; no data is directed to it. 


The CONSECUTIVE option specifies that the file is processed using the 
arrival sequence access path. Because CONSECUTIVE is the default, it 
could have been omitted. 


BUFSIZE(4) indicates that the maximum record length is four characters. 
When the file is opened, this is the amount of storage the program allocates 
in the buffer for a record. If your data is blocked, the program will run faster 
if you specify BLOCK instead of BUFSIZE; this is explained at note 5 of 
Figure 8-4 on page 8-7. 


RECORD data transmission is used with REL_FILE. 
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Using Display Files 


REL_FILE 1s declared with the DIRECT attribute because it is accessed 
non-sequentially. 


REL FILE is used for INPUT only; no data is directed to it. 


The CONSECUTIVE option specifies that REL_FILE has an arrival 
sequence access path. Because CONSECUTIVE is the default, the ENVI- 
RONMENT attribute can be omitted. 


STREAM data transmission is used with SYSPRINT. Stream files can only 
be accessed sequentially. 


The file receives OUTPUT only. It does not supply data to the program. 


The PRINT attribute indicates that the first character in the record is an 
ASA printer control character. 


IN_FILE is opened, with the TITLE option specifying 'RETRIEVE'. 
Because the library and member names are allowed to default, the first 
member of file RETRIEVE in the library list is opened. 


REL FILE is opened, with the TITLE option specifying 'MSTFILE'. 
Because the library and member names are allowed to default, the first 
member of file MSTFILE in the library list is opened. 


If the input data calls for the retrieval and printing of only one relative 
record, the READ is done using INPUT_WEEK as the relative record 
number. 


If the input data calls for the retrieval and printing of several relative records, 
the first relative record is retrieved using INPUT_WEEK as relative record 
number. 


For later READ statements an expression (INPUT WEEK + SEQ INCR) 
is used to specify each successive relative record number, until the last record 
asked for has been retrieved. 


SYSPRINT is implicitly opened by the first processing of the PUT state- 
ment. Any file not already opened is implicitly opened by the first data 
transmission statement which accesses it. It is, however, a good practice to 
explicitly open all your files. 


When using a display file, there are two file organizations you can specify by using 
the ENVIRONMENT options CONSECUTIVE and INTERACTIVE. There are 
also two file access methods you can specify by using the DECLARE statement 
attributes SEQUENTIAL and SEQUENTIAL KEYED. The input/output state- 
ment options allowed with each combination of these are shown in 

Appendix C, “Valid Combinations of Options for Input/Output Statements.” The 
combination of INTERACTIVE SEQUENTIAL KEYED 1s mainly used for sub- 
files. Subfiles are described in Programming: Data Management Guide. 


Other ENVIRONMENT options you specify can affect the input/output statement 
options you are able to use. If you specify NOINDARA, you cannot specify the 
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OPTIONS parameter INDICATORS, and if you specify BUFSIZE, the SET 
option of the input/output statements is affected. ENVIRONMENT parameters 
and the OPTIONS option are discussed in Chapter 7, “File Declaration and 
Input/Output,” while other input/output statement options are discussed in “Record 
Data Transmission” on page 11-8. 


Externally Described Display Files 


Just as with externally described data base files, you can specify the ENVIRON- 
MENT option DESCRIBED with externally described display files. A description 
of this option is in Chapter 7, “File Declaration and Input/Output,” while level 
checking is discussed in Chapter 6, “AS/400 PL/I File and Record Management.” 


Example of Using a Display File 


TR Internationg! Business Mochines 


The following program uses a display device file to process customer inquiries. 


AS/400 DATA DESCRIPTION SPECIFICATIONS cxa1-a91 -0 UM 0504 
*Number of sheets per pad may vary alightly. 


OO Description Poet 
sc encuico a (a 


st Ana sd /Comment (A/O/ 


As| CUSTOMER MASTER IINQUIR 
Seen i 


aA 48 47 2 09 37 91 52 3) 54 A Ad ST AA S38 OO 1 67 6) 64 iS Oh GT SS 0 71 72 739 Oe 


i a i aD GE ea ea 
ei cusPMT| {ff tt ty] 
a i 


aaa amv 
| AL 


Se ese eee ieee oes 


ec el ee: 
ake } "CUSTOMER NUMBER‘ 
ERRMSG( ‘CUSTOMER NUMBER NOT FOUND: 


Figure 8-9 (Part 1 of 5). Display File DDS and Customer Inquiry Program 
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TRY International Business Mochines AS/400 DATA DESCRIPTION SPECIFICATIONS oe eMed Wh USA, 


aNureber of uheeta per pod may vory elightly. 


== er 
ge eae ea a 


Ri Be AEM eM = ye 
| tf tt 14) SY STATE! 

STATE | | RO Ut Ba 
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EDT COE (0) ee 
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Figure 8-9 (Part 2 of 5). Display File DDS and Customer Inquiry Program 
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‘S 5728PL1 RO@1 M66 880715 PL/I Source Listing LP1420/LP1420 11/30/87 15:35:35 Page 2 
LP1426: PROCEDURE; DI$e6160 
Include SEQNBR STMT.SUBS BLK BN DO RE Pe i's Li bie eee ek vad Pesce Oe beat ak cAewee tl eau Decent eee Oines bese e] et eetecerd Date 
108 1 LP1420: PROCEDURE; DI$G0166 830817 
200 DI$08176 
300 /* FILE DECLARATIONS */ DI$60180 
4002 11 DECLARE 2 4 DIS00190 
508 1 1 CUSMINQ FILE RECORD SEQUENTIAL UPDATE ENV(INTERACTIVE), DIS@0200 840301 
600 2.1 1 <1 CUSMSTP FILE RECORD DIRECT INPUT ENV(INDEXED DESCRIBED); DI1$00210 830919 
700 5 8 Bj D1s0@220 
808 /* RECORD DECLARATIONS */ DI$86230 
900 3 1 1 DECLARE DIS00246 
1660 11 1 CUSTOMER_PROMPT, DIs9e258 
1100 % INCLUDE CUSMINQ(CUSPMT, INPUT, , COMMA) ; DIS80260 831606 
CUSPMT + 106 [® ennneenen----- 22-222 2-222 -- = 2-2 5 22-2 = 22 == + === == */ 
CUSPMT + 200 /* DEVICE FILE: CUSMINQ.LP1420 x/ 
CUSPMT + 300 /* FILE CREATION DATE: 87/11/30 x/ 
CUSPMT + 4800 /*® RECORD FORMAT: CUSPMT */ 
CUSPMT + 500 /* RECORD FORMAT SEQUENCE ID: 12E4847185567 x/ 
CUSPMT + 6006 [®  wennnnn nnn nen nn - o-oo oo $= o-oo ee ee ee ee = += == === -- x/ 
CUSPMT + 700 /* INDICATORS FOR FORMAT CUSPMT =/ 
CUSPMT + 800 /* INDICATOR 63 End of Program */ 
CUSPMT + 900 /* INDICATOR 99 Customer number not found: press Reset, then 
CUSPMT + 1000 enter x/ 
CUSPMT + 1100 [* ------- Customer Prompt------------------------------------------- x/ 
CUSPMT + 1260 3.1 11 15 CUST CHAR(5), /* CUSTOMER NUMBER x/ 
1290 3.2 11 1 CUSTOMER_INDICATORS, DIS$00258 831006 
1300 %INCLUDE CUSMINQ(CUSPMT, INDICATORS, , COMMA) ; DI$66260 831006 
CUSPMT + 100 [B® ewww nnn wn en nnn nnn nnn nn on nnn nnn nn nnn non nn neo ee neo een eee ee */ 
CUSPMT + 2006 /* DEVICE FILE: CUSMINQ.LP1420 */ 
CUSPMT + 300 /* FILE CREATION DATE: 87/11/30 x 
CUSPMT + 400 /* RECORD FORMAT: CUSPMT */ 
CUSPMT + 560 /* RECORD FORMAT SEQUENCE ID: 12€4847185567 */ 
( CUSPMT + 660 [* ------- Customer Prompt------------------------------------------- */ 
CUSPMT + 780 3.3 11 15 INO1 PIC ‘'9', /* End of Program */ 
CUSPMT + 866 3.4 1 1 15 IN@2_IN98 CHAR(97), /* UNDEFINED INDICATOR(S) */ 
CUSPMT + 9006 3.5 11 15 IN99 PIC '9', /* Customer number not found: 
CUSPMT + 1006 press Reset, then enter x/ 
1466 3.6 1 il 1 CUSTOMER_FIELDS, D1$80278 
1508 SINCLUDE CUSMINQ(CUSFLDS, OUTPUT, , COMMA) ; DIS00286 831006 
CUSFLDS + 160 [®  wnnen nono no-no ono on o-oo oo oe oo ee oo oo ooo eo oe eo = 5 == == - */ 
CUSFLDS + 206 /* DEVICE FILE: CUSMINQ.LP1426 */ 
CUSFLDS + 3086 /* FILE CREATION DATE: 87/11/30 */ 
CUSFLDS + 400 /* RECORD FORMAT: CUSFLDS x/ 
CUSFLDS + 566 /* RECORD FORMAT SEQUENCE ID: 1BBCFB695D44B *. 
CUSFLDS + 660 [® --22--2------ 22-22-2222 oo oo eo oo eo ooo eee oo oo ee e+ */ 
CUSFLDS + 700 /* INDICATORS FOR FORMAT CUSFLDS */ 
CUSFLDS + 806 /* INDICATOR 63 End of Program x/ 
C CUSFLDS + 900 [*® ------- Customer Display------------------------------------------ */ 
CUSFLDS + 1000 3.7 11 15 NAME CHAR(25), /* CUSTOMER NAME */ 
CUSFLDS + 1100 3.8 1 1 15 ADDR CHAR(20), /* CUSTOMER ADDRESS */ 
CUSFLDS + 1200 3.9 1 1 15 CITY CHAR(26), /* CUSTOMER CITY */ 
CUSFLDS + 1300 3.18 1 1 15 STATE CHAR(2), /* STATE */ 
CUSFLDS + 1400 3.11 1 1 15 ZIP PIC '9999R', /* ZIP CODE x/ 
CUSFLDS + 1500 3.12 1 il 15 ARBAL PIC '999999V9R', /* ACCTS REC BALANCE */ 
1666 3.13 1 1 1 CUSTOMER_MASTER_RECORD, DI$60296 
Figure 8-9 (Part 3 of 5). Display File DDS and Customer Inquiry Program 
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Include 


CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSHST 
CUSMST 
CUSHST 
CUSMST 
CUSHMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSMST 
CUSHST 
CUSHST 


+e eeeeeeeeeeoeeoeeerereereete et 


SEQNBR STMT. 


1706 
100 
200 
306 
400 
506 
600 
708 
800 
900 

1000 

1106 

1200 

1300 

1480 

1500 

1608 

1700 

1806 

1900 

2000 

2100 

2200 

2300 

2400 

2500 

1800 

1906 

2000 

2100 

2208 

2308 

2400 

2500 

2600 

2700 

2800 

2900 

3008 

3108 

3200 

3306 

3408 

3500 

3600 

3760 

3800 

3900 

4008 

4100 

4208 

4300 

44608 


2 & 
e 
Ne 


— — — jp 


Mm NN De 


SUBS BLK BN DO 


— — — — — 


NN MR ee 


11/36/88 15:35:35 


OC PP Pee ee: ee 


15 ARBAL PIC '999999V9R', 
15 ORDBAL PIC '999999V9R', 
15 LSTAMT PIC '999999V9R', 
15 LSTDAT PIC '99999R', 


CUSTOMER NUMBER 

DDS - KEY FIELD 

CUSTOMER NAME 

CUSTOMER ADDRESS 

CUSTOMER CITY 

STATE 

ZIP CODE 

CUSTOMER NUMBER SEARCH CODE 
CUSTOMER TYPE 1=GOV 2=SCH 


PL/I Source Listing LP1426/LP1426 
LP1426: PROCEDURE; 
REF ere Migs ne wel vet Pena eeeet eas beas 
%&INCLUDE CUSMSTP(CUSMST, RECORD) ; 
/* 
/* PHYSICAL FILE: CUSMSTP.LP1420 
/* FILE CREATION DATE: 87/11/30 
/*® RECORD FORMAT: CUSMST 
/* RECORD FORMAT SEQUENCE ID: 4AA7C9OESBBIE 
/* 
15 CUST CHAR(5), /* 
/* 
15 NAME CHAR(25), /* 
15 ADDR CHAR(20), /* 
15 CITY CHAR(20), /* 
15 STATE CHAR(2), [* 
15 ZIP PIC '9999R', /* 
15 SRHCOD CHAR(6), /* 
15 CUSTYP PIC 'R', /* 


3=BUS 4=PVT 5=0T 


/* 
/* 
/* 
/* 


ACCTS REC BALANCE 

A/R AMT IN ORDER FILE 
LAST AMT PAID IN A/R 

LAST DATE PAID IN A/R 


15 CRDLMT PIC '999999V9R', /* CUSTOMER CREDIT LIMIT 
15 SLSYR PIC '99999999V9R', 
/* CUSTOMER SALES THIS YEAR 
15 SLSLYR PIC '99999999V9R'; 
/* CUSTOMER SALES LAST YEAR 
/* INDICATOR FLAGS */ 
DECLARE 
1 INDICATOR_FLAGS STATIC, 
2 OFF PICTURE '9' INIT(®), 
2 ON PICTURE '9' INIT(1); 
/* BUILT-IN FUNCTIONS */ 
DECLARE 
ONCODE BUILTIN; 


ON KEY (CUSMSTP) 
BEGIN; 
ON ERROR SYSTEM; 
IF ONCODE = 51 THEN 
IN99 = ON; 
END; /* BEGIN */ 


/* MAIN PROGRAM */ 
opeN ft 

FILE (CUSMINQ); /* UPDATE */ 
OPEN [fl 

FILE (CUSMSTP); /* INPUT */ 


INO3 = OFF; 
IN99 = OFF; 
DO WHILE(INO3 = OFF); 


Figure 8-9 (Part 4 of 5). Display File DDS and Customer Inquiry Program 
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*/ 
a 
*/ 
*/ 
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+ 


ar 
*/ 


Page 


D1S08166 


ete cee eMeetee eS Date 


D1S86300 


D1$06316 
DIS$08320 
D1S$00336 
D1S80340 


DIS06350 831906 
DIS00366 831606 


DIS@0376 
DI1S00386 
D1$08396 
DIS$00408 
DIS$00418 
D1$68426 
D1S$06436 
DIS$90446 
01$00456 
DI$80460 
D1S$66476 
DIS$06486 
DISe0496 
DIS06560 


DIS$00516 830919 


D1S$86526 


DI$00536 836919 


01S00546 
DIS6655e 
DIS96560 
DI$60576 


J 


C 
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Include 
4500 
4660 
4708 
4800 
4900 
5006 
5100 
5200 
5300 
5400 
5506 
5600 
5700 
5800 
5900 
6000 
6100 
6208 
6300 
6400 
6500 
6600 
6700 
6800 
6900 
7000 
7100 
7268 
7300 
7400 
7500 


15 


29 


i ot opt 


— ps pe 


1 


— i of 


a a oe) 


1 


SEQNBR STMT.SUBS BLK BN DQ 


RH MO Ww Ww Ww &w Ww Ww WPA PD K&R Re ee 
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PL/I Source Listing LP1420/LP1426 11/30/88 15:35:35 Page 
LP1420: PROCEDURE; DISe0160 
co. ae, ee Cen, ey aera eek Per eer, eer ane Sees. Pear. Omer Per ere, Dante Gre de Perea «| 
DIS60580 
/* DISPLAY THE SCREEN */ bIsees90 
FR] «= WRITE FILE (CUSMINQ) FROM (CUSTOMER_PROMPT) DIS@0600 
OPTIONS (RECORD('CUSPMT') INDICATORS(CUSTOMER_INDICATORS)); D1S80610 
14] DISe0620 
/* READ AND PROCESS SCREEN */ DIS00630 
IN99 = OFF; D1se0646 
FE) READ FILE (CUSMINQ) INTO (CUSTOMER_PROMPT) DIS00650 
OPTIONS (RECORD('CUSPMT') INDICATORS(CUSTOMER INDICATORS)); DIS00660 
IF INO1 = OFF THEN DI1S00670 
D0; DISe0680 
READ FILE (CUSMSTP) INTO {CUSTOMER_MASTER_RECORD) DISe0690 
KEY (CUSTOMER_PROMPT .CUST) ; 

19 IF IN99 = OFF THEN DISe0700 
DO; DIS@0710 
CUSTOMER FIELDS = CUSTOMER_MASTER RECORD, BY NAME; DIs60720 
WRITE FILE (CUSMINQ) FROM (CUSTOMER_FIELDS) D1$00730 
OPTIONS(RECORD('CUSFLDS')); D1S00740 
20 READ FILE (CUSMINQ) INTO (CUSTOMER_FIELDS) D1S00750 
OPTIONS (RECORD( 'CUSFLDS') D1S00760 

INDICATORS(CUSTOMER_INDICATORS)) ; 
END; /* DO */ DISe077@ 
END; /* DO */ D1S00780 
END; /* DO WHILE */ DIS60790 
DISe0800 
CLOSE DIS00810 
FILE (CUSMINQ); DIse0820 
CLOSE D1se0830 
FILE (CUSMSTP) ; D1se084a 
D1se0850 
END LP1420; 01s90860 


Figure 8-9 (Part 5 of 5). Display File DDS and Customer Inquiry Program 


CUSTOMER MASTER INQUIRY 


CUSTOMER NUMBER 12345 


USE F3 TO END PROGRAM, USE ENTER KEY TO RETURN TO PROMPT SCREEN 


NAME 
ADDRESS 85 NOWHER 
CITY  SCARBERIA 
STATE ON 
A/R BALANCE 


EVANS, T.J. 


E RD. 


ZIP CODE 


111,111.11 


76889 


4 


Date 


831606 


831606 


831066 
831606 


831006 
831006 


830817 


Figure 8-10. Display Produced Using Display File DDS and Customer Inquiry Program 


RECORD data transmission is used with CUSMINQ. 
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The SEQUENTIAL access method is used with CUSMINQ. The records 
are read in using the arrival sequence access path. 


The data transmission mode is specified as UPDATE, since CUSMINQ is 
used for both input and output. 


The ENVIRONMENT attribute is specified with the INTERACTIVE 
option. Both READ and WRITE statements are allowed, in this case to 
provide prompt screens and read input which is entered on the work station 
screen. 


RECORD data transmission is used with CUSMSTP. The pps for 
CUSMSTP will be found at Figure 8-1 on page 8-3. 

[J] CUSMSTP is declared with the DIRECT attribute, because it is accessed 
non-sequentially. 

CUSMSTP is used for INPUT only: no output is directed to it by the 
program. 

FE} INDEXED specifies that the file is processed using the keyed sequence access 
path. 

EF] DESCRIBED indicates that external record format definitions are used in the 
program. 

CUSMINQ is opened. The UPDATE option is omitted, because it is speci- 
fied as an attribute in the file declaration. 

CUSMSTP is opened. The INPUT option is omitted, because it is specified 
as an attribute in the file declaration. 

The prompt screen is displayed by writing to CUSMINQ, the file associated 
with the display device. 

The record format named CUSPMT is used. 

The indicators in CUSTOMER_INDICATORS, a structure declared using 
the %INCLUDE statement, are passed to the display device. 

The information entered on the work station screen is read into 
CUSTOMER_PROMPT. 

The record format named CUSPMT is used. 

The indicators are returned from the display device to the structure 
CUSTOMER_INDICATORS. 

If INO1 has a value of zero, that is, if the user has not requested that the 


program end, CUSTOMER _MASTER_RECORD is read in from file 
CUSMSTP using the key the user has provided 
(CUSTOMER_PROMPT.CUST). 


If IN99 has a value of zero, that is, if the user has specified a valid key, then 
the necessary fields from CUSTOMER_MASTER_RECORD are placed in 
CUSTOMER_FIELDS, which is then written to the display device using 
record format CUSFLDS. If IN99 has a value of one, control is passed to 
the top of the loop (statement 15) and the prompt screen displays the error 
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message specified on the DDs reporting that the customer number has not 
been found, and requesting a valid number for input. 


CUSTOMER FIELDS is read back in from CUSMINQ, and the indicators 
are returned from the display device to the structure 
CUSTOMER_INDICATORS. If the user requests that the program end, 
the next test of the value of INO] halts running. 


Example of Using a Subfile for Displaying Data 


IRM OR ae ea AS/400 DATA DESCRIPTION SPECIFICATIONS welenpar nie a 


eNureber af ahegin per pad vary eng: 


TTEM | 2TEXTC'ITEM NUMBER‘) = 
| a QTYoRD| [| 3y 010 eT EXTS FOUANTITY ORDERED 
OA ED TCDE CS) esr 
RSP Sty eter eer eet feeb ————— 
ATT TT TT TT Price | TTT U6Y aT 10 46 TEXTE “SELLING PRICE 
rT tt tT ty TG EDTOCDEC) 
ALT] tt tt] UL EXTENS, | ae BED TOBE 
Att |__|} TEx? Et EXTENSION AMOUNT OF QTYORD 4 EXT( "EXTENSION AMOUNT OF QTYORD e 
Ali] ff ft yey Tt | {| | 
—— rt Se oo 
a’ \a HL fi SUBerty tJ P| TT TT IS FLOTL(SUB1) 
ee 


ee 
aceon HT a NP A Fa 


Figure 8-11 (Part 1 of 15). Program and Supporting DDS for Using Subfiles 
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TRH AS/400 DATA DESCRIPTION SPECIFICATIONS GX21-9801-0 UN/050¢ 


= ; . . Printed ln U.S.A, 
= International Business Machines Number of sheets per pod reay vary slighily. 


OO Description rom ot 
[Proercwmer tee ie 


Usage (6/O/1/B/H/NAN/P) 


Gecimal 


& Positions 


& Onta Type We A/P/S/B/F ALS/V/NILW/D/M) 


a Ae ee ae SE ESIACR I oe 
es es SR PAG CUA) oe Se 
fe Ne Se SEL END 
a ep GAY 
are Se es eae hee 
1 ee Gon ed 


A) NA pO 
PTT TTT TT ROL CUP(S7 “CONTINUE DISPLAY‘ 

TOA TT TT tr A088 "END OF PROGRAM") 
PUA TTT TT CS ETOFF (S57 ‘DISPLAY SUBFILE*) 
fT CUA TT TT TT CS ETOFF(S8S 'OFF=DISPLAY SUBCTL ON-CL+ 
fT CUA EE TT TT {EAR sSUBFILE' 
rT COU Tt 2 EXISTING ORDER INQUIRY’  —ss 
PUA TT 2 ORDER' 
[CUA CUT ST tT orDe—eR | [| [fh USN op) 63. OBTEXTC' ORDER NUMBER’ 
| CUA BT LT CT ERRMSG ( “ORDER NUMBER NOT FOUND’ 61) 
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A 82 tt RRMSG(*NO CUSTOMER RECORD FOUND FO+ 
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Figure 8-11 (Part 2 of 15). Program and Supporting DDS for Using Subfiles 


Tai AS/400 DATA DESCRIPTION SPECIFICATIONS nea panes iG aa: 
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mae Ss Ha aT xTe ‘CUSTOMER NUMBER® 
NAME _| aaa terexre co OMER_NA 
[4 16TeE 
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as HT STATE LBB ERTC STATES ss 

es Se eee ee: 

a et eo 

htt LT eRp AMT {| _8y 214 S51TEXT( ‘TOTAL DOLLAR AMOUNT OF THE + 

ees | a a ee Pt ORDERS) 

Ee ese eee ee eo DTCDE(J $) 

fae Ach ee ie ee ei el ii a 
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Figure 8-11 (Part 3 of 15). Program and Supporting DDS for Using Subfiles 
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( Figure 8-11 (Part 4 of 15). Program and Supporting DDS for Using Subfiles 
TRH ee Se ee et ee AS/4900 DATA DESCRIPTION SPECIFICATIONS eee fe paged nA 
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~S Figure 8-11 (Part 5 of 15). Program and Supporting DDS for Using Subfiles 
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Figure 8-11] (Part 6 of 15). Program and Supporting DDS for Using Subfiles 
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Figure 8-11 (Part 7 of 15). Program and Supporting DDS for Using Subfiles 
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Include 


SUB1 
SUB1 
SUB1 
SUB1 
SUB1 
SUB1 
SUB1 
SUB1 
SUB1 
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SUB1 
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SUBCTL1 
SUBCTL1 
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SUBCTL1 
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SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
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Figure 


SEQNBR STMT.SUBS BLK BN DO 
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PL/I Source Listing 
LP1422: PROCEDURE; 
+., 


LP1422: PROCEDURE; 


Ke, 


E 
/* 
/* 
/* 
/* 
/* 
/* 


9 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


1d 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


otecceleces 


codecs 


LP1422/LP1422 11/36/88 15:39:54 


erent! Cae, See 


/* FILE DECLARATIONS */ 


DECLARE 


ORD220D FILE RECORD SEQUENTIAL KEYED UPDATE ENV(INTERACTIVE), 
ORDHDRP FILE RECORD DIRECT INPUT ENV(INDEXED DESCRIBED), 
ORDDTLP FILE RECORD DIRECT INPUT ENV(INDEXED DESCRIBED), 
CUSMSTP FILE RECORD DIRECT INPUT ENV(INDEXED DESCRIBED); 


B 


/* RECORD DECLARATIONS */ 


DECLARE 


1 SUB1_RECORD, 
%INCLUDE ORD22@D(SUB1, OUTPUT, , COMMA) ; 

DEVICE FILE: ORD220D.LP1422 

FILE CREATION DATE: 87/11/30 

RECORD FORMAT: SUB1 


RECORD FORMAT SEQUENCE ID: 140C3D225CC47 
15 ITEM PIC '9999R', /* Item Number 
15 QTYORD PIC '99R', /* Quantity Ordered 
15 DESCRP CHAR(30), /* Item Description 
15 PRICE PIC '9999V9R', /* Selling Price 
15 EXTENS PIC '999999V9R', /* Extension Amount of QTYORD * 


PRICE 


1 SUBCTL1_RECORD_INPUT, 
“INCLUDE ORD220D(SUBCTL1, INPUT, , COMMA) ; 
DEVICE FILE: ORD220D.LP1422 
FILE CREATION DATE: 87/11/36 
RECORD FORMAT: SUBCTL1 
RECORD FORMAT SEQUENCE ID: lAC3AF315286B 


INDICATORS FOR FORMAT SUBCTL1 


INDICATOR 
INDICATOR 
INDICATOR 
INDICATOR 
INDICATOR 
INDICATOR 
INDICATOR 
INDICATOR 


No lines for this order 

Display Subfile 

Off=Display Subct] On=Clear Subfile 
Order number not found 

No customer record found for this order 
Continue Display 

End of Program 


15 ORDER 
1 SUBCTL1_RECORD_OUTPUT, 
% INCLUDE ORD220D(SUBCTL1, OUTPUT, , COMMA) ; 
DEVICE FILE: ORD220D.LP1422 
FILE CREATION DATE: 87/11/36 
RECORD FORMAT: SUBCTL1 
RECORD FORMAT SEQUENCE ID: 1AC3AF315286B 


INDICATORS FOR FORMAT SUBCTL1 


PIC '9999R', /* Order Number 
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Page 2 
PRIQ0160 


Fes a ee ee Ae ee ao Date 


PRI00160 830817 
PRIQ0178 
PRI00180 
PR1I00190 
PRI90200 830609 
PRI96210 830919 
830919 
830919 
PRI60220 
PR190236 
PRI00Q246 
PRIQ0250 
PRI60260 830919 


PRI0@278 830609 
PRI80280 830919 


830609 
830919 


2 


C 
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Include 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
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SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
SUBCTL1 
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SEQNBR STMT.SUBS BLK BN DO 


800 

900 
1808 
1100 
1200 
1300 
1440 
1500 
1608 
1700 
1800 
1900 
2000 
2100 
2200 
2300 
2400 
2506 
2606 
2700 
2806 
29080 
3008 
3180 
3200 
3300 
3460 
3500 
1800 
1900 

100 

200 

308 

400 

500 

600 

709 

800 

900 
1060 
1100 
1208 
1308 
1468 
1580 
1608 
1760 
1890 
1989 
2000 
2100 
2200 
2000 
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PL/I Source Listing 
LP1422: PROCEDURE; 


Kew, 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Bers er, rarer 


USING DISPLAY FILES 


LP1422/LP1422 11/30/88 15:39:54 


fet aied oecs Pea e eden Pekx 


INDICATOR 45 a} 
INDICATOR 47 No lines for this order */ 
INDICATOR 57 Display Subfile x] 
INDICATOR 58 Off=Display Subct] On=Clear Subfile */ 
INDICATOR 61 Order number not found xf 
INDICATOR 62 No customer record found for this order xf 
INDICATOR 97 Continue Display */ 
INDICATOR 99 End of Program */ 
qc ene nen en enn nnn nnn non nn nn oo eee eee = == === ----- 2 ---- */ 
15 ORDER PIC '9999R', /* Order Number x / 
15 ORDDAT PIC '99999R', /* Date Order was Entered a A 
15 CUST CHAR(5), /* Customer Number */ 
15 NAME CHAR(25), /* Customer Name */ 
15 ADDR CHAR(2@), /* Customer Address */ 
15 CITY CHAR(28), /* Customer City */ 
15 STATE CHAR(2), /* State */ 
15 ZIP PIC '9999R', /* Zip Code */ 
15 ORDAMT PIC '999999VOR', /* Total Dollar Amount of the 
Order */ 
15 STSORD CHAR(12), 
15 STSOPN CHAR(12), 
15 CUSORD CHAR(15), /* Customer Purchase Order Number 
*« 
/ 
15 SHPVIJA CHAR(15), /* Shipping Instructions =} 
15 PRTDAT PIC '99999R', /* Date Order was Printed */ 
15 INVNUM PIC '9999R', /* Invoice Number */ 
15 ACTMTH PIC 'OR', /* Accounting Month of Sale */ 
15 ACTYR PIC 'OR', /* Accounting Year of Sale */ 
1 SUBCTL1_INDICATORS, 
%INCLUDE ORD220D(SUBCTL1, INDICATORS, , COMMA) ; 
ei cataract Nea ices a a ae Se ae */ 
DEVICE FILE: ORD220D.LP1422 */ 
FILE CREATION DATE: 87/11/30 */ 
RECORD FORMAT: SUBCTL1 */ 
RECORD FORMAT SEQUENCE 1D: 1AC3AF315286B of | 
SI ie Tae ent eee ae ENS eta NTS Ned PRIS charts PEN at eR et af 0 Met OAT x / 
15 INO1_IN44 CHAR(44), /* UNDEFINED INDICATOR(S) */ 
15 IN45 PIC ‘9', 
15 IN46_IN46 CHAR(01), /* UNDEFINED INDICATOR(S) */ 
15 IN47 PIC '9', /* No lines for this order = 
15 IN48 IN56 CHAR(09), /* UNDEFINED INDICATOR(S) */ 
15 IN57 PIC '9', /* Display Subfile */ 
15 IN58 PIC '9', /* Off=Display Subct] On=Clear 
Subfile a | 
15 IN59_IN60 CHAR(02), /* UNDEFINED INDICATOR(S) */ 
15 IN61 PIc '9', /* Order number not found it | 
15 IN62 PIC '9', /* No customer record found for 
this order */ 
15 IN63_IN96 CHAR(34), /* UNDEFINED INDICATOR(S) */ 
15 IN97 PIC '9', /* Continue Display */ 
15 IN98_IN98 CHAR(@1), /* UNDEFINED INDICATOR(S) */ 
15 IN99 PIC '9', /* End of Program */ 
1 ORDER_HEADER, 
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USING DISPLAY FILES 
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Include 


ORDHDR 
ORDHOR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 
ORDHDR 


ORDDTL 
ORDDTL 
ORDDTL 
ORDBTL 
ORDDTL 
ORDDTL 
ORDDTL 
ORDDTL 
ORDDTL 
ORDDTL 
ORDOTL 
ORDDTL 
ORDOTL 
ORDDTL 
ORDDTL 
ORDDOTL 
ORDDTL 
ORDDTL 
ORDDTL 
ORDDTL 
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1200 

1366 

1400 

1506 

1600 

1760 

1800 

1906 

2600 

2160 

2200 

2380 

2400 

2500 

2600 

2700 

2800 

2906 

3060 

2208 

2300 
100 
200 
308 
400 
500 
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708 
800 
908 
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1100 
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1900 
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LP1422: PROCEDURE; 
Re Peat Lei ahs d Ol aoe S40 ee hee Fe ee Oe oF ed oe a eee Oia 
%INCLUDE ORDHDRP(ORDHDR, RECORD, , COMMA) ; 
/* pests Sa EAE a Da Che Bl AON Ll Ss aT A is ae DE A SS oD */ 
/* PHYSICAL FILE: ORDHDRP.LP1422 a 
/* FILE CREATION DATE: 87/11/36 x / 
/*® RECORD FORMAT: ORDHDR */ 
/* RECORD FORMAT SEQUENCE ID: 4F2FC74D337EB */ 
[* ------- Order Header Record--------------------------------------- */ 
15 CUST CHAR(5), /* Customer Number */ 
15 ORDER PIC ‘'9999R', /* Order Number */ 
/* DOS - KEY FIELD */ 
15 ORDDAT PIC ‘'99999R', /* Date Order was Entered x/ 
15 CUSORD CHAR(15), /* Customer Purchase Order Number 
* 
/ 
15 SHPVIA CHAR(15), /* Shipping Instructions */ 
15 ORDSTS PIC 'R', /* Order Status l=PCS 2=CNT 3=CHK 
4=RDY 5=PRT 6=PCK */ 
15 OPRNAM CHAR(10), /* Operator Name who entered the 
order *] 
15 ORDAMT PIC '999999V9R'’, /* Total Dollar Amount of the 
Order a | 
15 CUSTYP PIC 'R', /* Customer Type 1=G0V 2=SCH 
3=BUS 4=PVT 5=0TH */ 
15 INVNUM PIC '9999R', /* Invoice Number */ 
15 PRTDAT PIC '99999R', /* Date Order was Printed xf 
15 OPNSTS PIC 'R', /* Order Open Status 1=0PEN 
2=CLOSE 3=CANCEL */ 
15 TOTLIN PIC '99OR', /* Total Line Items in Order */ 
15 ACTMTH PIC 'OR', /* Accounting Month of Sale */ 
15 ACTYR PIC 'OR', /* Accounting Year of Sale */ 
15 STATE CHAR(2), /* State xf 
15 AMPAID PIC '999999V9R', /* Total Dollar Amount Paid */ 
1 ORDER DETAIL, 
%SINCLUDE ORDDTLP(ORDDTL, RECORD, , COMMA) ; 
| ae a Re Senet Pe Ce eR Oe yk ET ao Te ere */ 
/*® PHYSICAL FILE: ORDDTLP.LP1422 */ 
/* FILE CREATION DATE: 87/11/30 x/ 
/* RECORD FORMAT: ORDDTL x/ 
/* RECORD FORMAT SEQUENCE ID: 3CAOF801BF74E */ 
/[* ------- Order Detail Record--------------------------------------- */ 
15 CUST CHAR(5), /* Customer Number */ 
15 ORDER PIC '9999R', /* Order Number */ 
/* DDS - KEY FIELD xf 
15 LINNUM PIC '9OR', /* Line Number of line in order*/ 
/* DDS - KEY FIELD */ 
15 ITEM PIC '9999R', /* Item Number */ 
15 QTYORD PIC '9OR', /* Quantity Ordered big 
15 DESCRP CHAR(36), /* Item Description */ 
15 PRICE PIC '9999VOR', /* Selling Price */ 
15 EXTENS PIC *999999V9R', /* Extension Amount of QTYORD * 
PRICE x/ 
15 WHSLOC CHAR(3), /* Bin No. */ 
15 ORDDAT PIC '99999R', /* Date Order was Entered x/ 
15 CUSTYP PIC 'R', /* Customer Type 1=GOV 2=SCH 
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USING DISPLAY FILES 


C 5728PL1 R01 Me6 880715 PL/Y Source Listing LP1422/LP1422 11/30/88 15:39:54 Page 5 
LP1422: PROCEDURE; PR180160 
Include SEQNBR STMT.SUBS BLK BN DO sa PL EM BPA, Me ae, Dw ee, ney: CUE En Ae. PRP RE, ey Je Fem, eons OND) Ha 
ORDDTL + 2160 3=BUS 4=PVT 520TH */ 
ORDOTL + 2260 3.71 11 15 STATE CHAR(2), /* State */ 
ORDOTL + 2360 3.72 1 1 15 ACTMTH PIC '9R', /* Accounting Month of Sale */ 
ORDOTL + 2460 3.73 11 15 ACTYR PIC ‘OR', /* Accounting Year of Sale */ 
2406 3.74 1 1 1 CUSTOMER_MASTER, 
2500 % INCLUDE CUSMSTP(CUSMST,RECORD); 830603 
CUSMST + 100 [® 2--------------- 22-2222 2-2-3 3-2-2 2-5 5-3-5 +--+ */ 
CUSMST + 200 /* PHYSICAL FILE: CUSMSTP.LP1422 */ 
CUSMST + 300 /* FILE CREATION DATE: 87/11/30 */ 
CUSMST + 460 /* RECORD FORMAT: CUSMST */ 
CUSMST + 5600 /* RECORD FORMAT SEQUENCE ID: 4AA7C9QE9BB1E * / 
CUSMST + 660 [*® ------- CUSTOMER MASTER RECORD------------------------------------ */ 
CUSMST + 700 3.75 1 1 15 CUST CHAR(5), /* CUSTOMER NUMBER =] 
CUSMST + 860 /* DDS - KEY FIELD */ 
CUSMST + 900 3.76 1 1 15 NAME CHAR(25), /* CUSTOMER NAME */ 
CUSMST + 1000 3.77 1 1 15 ADDR CHAR(26), /* CUSTOMER ADDRESS */ 
CUSMST + 1100 3.78 1 1 15 CITY CHAR(26), /* CUSTOMER CITY */ 
CUSMST + 1200 3.79 1 1 15 STATE CHAR(2), /* STATE */ 
CUSMST + 1366 3.80 1 1 15 ZIP PIC '9999R', /* ZIP CODE */ 
CUSMST + 1400 3.81 1 1 15 SRHCOD CHAR(6), /* CUSTOMER NUMBER SEARCH CODE */ 
CUSMST + 1560 3.82 11 15 CUSTYP PIC 'R', /* CUSTOMER TYPE 1=G0V 2=SCH 
CUSMST + 1600 3=BUS 4=PVT 5=0T */ 
CUSMST + 1760 3.83 11 15 ARBAL PIC '999999V9R', /* ACCTS REC BALANCE */ 
CUSMST + 1860 3.84 1 1 15 ORDBAL PIC '999999V9R', /* A/R AMT IN ORDER FILE */ 
CUSMST + 1900 3.85 1 1 15 LSTAMT PIC '999999V9R', /* LAST AMT PAID IN A/R */ 
CUSMST + 2000 3.86 1 1 15 LSTDAT PIC '99999R', /* LAST DATE PAID IN A/R */ 
CUSMST + 21006 3.87 1 1 15 CRDLMT PIC '999999V9R', /* CUSTOMER CREDIT LIMIT */ 
CUSMST + 2200 3.88 1 1 15 SLSYR PIC '99999999V9R', 
CUSMST + 2300 /* CUSTOMER SALES THIS YEAR */ 
CUSMST + 2400 3.89 1 1 15 SLSLYR PIC '99999999V9OR'; 
CUSMST + 2500 /* CUSTOMER SALES LAST YEAR */ 
: 2600 830603 
2700 /* KEY STRUCTURE */ 830603 
2800 4 1 1 DECLARE 830603 
2900 1 1 1 DETAIL_KEY, 830602 
3060 4.1 1 1 2 D_ORDER PICTURE '9999R', 831011 
3160 4.2 1 1 2 D_LINNUM PICTURE '99R'; 831611 
3200 PRI66330 
3300 /* INDICATOR FLAGS */ PR180340 
3400 5 1 1 DECLARE PRI80350 
3560 1 1 1 INDICATOR_FLAGS STATIC, PRI00360 
3660 5.1 1 1 2 OFF PICTURE '9' INIT(6), PRI80378 831007 
3706 5.2 eae 2 ON PICTURE '9' INIT(1); PR166380 831607 
3800 PRI86396 
3900 /* BUILT-IN FUNCTIONS */ PR160470 830662 
4660 6 1 1 DECLARE PRI66480 
4100 11 ONCODE BUILTIN, PRI66496 831611 
4200 6.1 1 1 DECIMAL BUILTIN; 831011 
4300 830602 
4400 /*® PROGRAM VARIABLES */ PRI 66580 
4560 7 1 1 DECLARE PR100590 
4600 1 1 OPNSTAT (3) STATIC CHAR(12) INIT('1-OPEN', PR160660 836609 
4760 1 1 '2-CLOSED', 830609 
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Include SEQNBR STMT.SUBS BLK BN DO 
4800 1 <2 
4900 7.1 1 1 
5000 11 
5160 1 1 
5200 1 1 
5300 11 
5400 11 
5500 1 1 
5600 1 1 
5700 1 1 
5800 = 7.2 1 1 
5900 
6000 = 8 11 
6100 1 1 
62009 2 2 
6300 =: 10 2 2 
6460 22 
6500 = 11 221 
6600 12 221 
6700 §=«-13 221 
680014 2 2 
6900 
7000 «15 11 
7100 ae 
7200 «= «16 3 2 
7300017 3 2 
7400 3 2 
7500 3 2 
7600 «= «18 321 
7700 = «19 321 
7800 «= 20 324 
7900 «= 21 3 2 
8000 3 2 
8100 22 3 2 
8200 
8300 
8400 23 11 
8500 1 1 
8600 24 4 2 
8700 25 4 2 
8800 4 2 
8900 26 421 
9000 27 421 
9100 28 421 
9200 © 29 4 2 
9300 
9400 © 30 1 1 
9500 1. 1 
9600 
9700 31 Lt 
9800 1 1 
9900 

16000 


LP1422: PROCEDURE; 


RSMo Lacie eben este wt ed 


ORDSTAT(9) 


READ_CHK 


ON KEY (ORDHDRP) 
BEGIN; 
ON ERROR SYSTE 


IF ONCODE = 51 THEN 


DO; 
IN61 = ON; 
GOTO DSP; 
END; /* DO * 
END; /* BEGIN */ 


ON KEY (ORDDTLP) 
BEGIN; 
ON ERROR SYSTE 


IF ONCODE = 51 THEN 


M; 


/ 


Ms 


LP1422/LP1422 


A ee ren oe 


11/36/88 15:39:54 


"3-CANCELLED'), 


STATIC CHAR(12) INIT('1-IN PROCESS’, 


CHAR(5); 


IF READ_CHK = 'READ1' THEN 


DO; 
IN47 = 0 
GOTO DSP 


END; /* DO */ 


ELSE 
GOTO SUB; 
END; /* BEGIN */ 


ON KEY(CUSMSTP) 
BEGIN; 
ON ERROR SYSTE 


IF ONCODE = 51 THEN 


DO; 
IN62 = ON; 
GOTO DSP; 
END; /* DO * 
END; /* BEGIN */ 


ON ENDFILE(ORD220D 
GOTO SUB; 


ON ENDFILE(ORDDTLP 
GOTO SUB; 


/* MAIN PROGRAM 


N; 


M; 


i 


) 


) 


*/ 


*2-CONTINUED', 
*3-CREDIT CHK’, 
"Q-READY PRT', 
'5-PRINTED', 
'6-PICKED'’, 
"7-INVOICED', 
"8-INVALID', 
"9-CANCELLED'), 
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830602 
830602 
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830602 
830602 
830602 
830602 
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830602 
830602 
830602 
830602 
830602 
830602 
830602 
830662 
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830602 
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LP1422: PROCEDURE; PR190160 

Include SEQNBR STMT.SUBS BLK BN DO %<..4.... Lice ctecscQeeccbeccedecsetececbecc tens sSeccctesccOossctecceTePecteee 8 Date 
19108 ©. 32 11 SUBCTL1_INDICATORS = OFF; /* SET ALL INDICATORS OFF */ 880415 
18200 880415 
19300 «© 33 11 SUBCTL1_RECORD_OUTPUT.ORDDAT = 0; 880415 
19408 «©9334 11 SUBCTL1_RECORD_OUTPUT.ORDAMT = 9; 880415 
19500 «= 35 11 SUBCTL1_RECORD_OUTPUT.PRTDAT = 0; 880415 
10608 36 11 SUBCTL1_ RECORD OUTPUT.ZIP = 0; 880415 
10700 «= 37 11 SUBCTL1_ RECORD OUTPUT. INVNUM = 0; 880415 
19880 6-38 1 1 SUBCTL1_RECORD_OUTPUT.ACTMTH = 0; 880415 
19988 ©=- 39 1a SUBCTL1_RECORD_OUTPUT.ACTYR = 0; 880415 
11000 880415 
11100 «= 48 1 1 FH open PR180690 880415 
11200 11 FILE (ORD220D); /* UPDATE */ PRIG0700 880415 
11300041 1 1 (FR open PR100710 880415 
11498 1 1 FILE (OROHDRP); /* INPUT */ PR168728 880415 
11500 = 42 1 1 FR open 880415 
11600 11 FILE (ORDDTLP); /* INPUT */ 880415 
11700 43 1 1 FR open 880415 
11808 11 FILE (CUSMSTP); /* INPUT */ 880415 
11900 PRI60750 880415 
12000 «8944 1 1 [RH DSP: DO WHILE(ING9 = OFF); PRIO0760 880415 
12100 PRI60770 880415 
12208 8945 111 FG) WRITE FILE (ORD226D) FROM (SUBCTL1_RECORD OUTPUT) PRI60780 880415 
12306 111 OPTIONS(RECORD('SUBCTL1') INDICATORS(SUBCTL1_INDICATORS)) ;PRI60790 880415 
12400 «46 ae ae | IN58 = OFF; 880415 
12500 647 111 FR] READ FILE (ORD220D) INTO (SUBCTL1_RECORD_INPUT) PR100800 880415 
12600 111 OPTIONS(RECORD('SUBCTL1') INDICATORS(SUBCTL1_INDICATORS)); PRI6@810 880415 
12700 © 48 111 FE! READ FILE (ORDHDRP) INTO (ORDER_HEADER) PR100820 880415 
12888 111 KEY(SUBCTL1_RECORD_INPUT.ORDER) OPTIONS (KEYSEARCH(EQUAL)); 880415 
12908 649 111 KR SUBCTL1_RECORD OUTPUT = ORDER_HEADER, BY NAME; 880415 
13008 © 58 111 D_ORDER = SUBCTL1_RECORD_OUTPUT. ORDER; PR100830 880415 
1310851 111 D_LINNUM = 1; PRI60840 880415 
13200 = 52 111 READ_CHK = 'READI'; PRI00850 880415 
. 13300 453 oe ie | Al READ FILE (ORDDTLP) INTO (ORDER_DETAIL) KEY(DETAIL_KEY) PRI00860 880415 
134060 111 OPTIONS(KEYSEARCH(EQUAL) NBRKEYFLDS(2)); 880415 
13500 54 111 FB] READ FILE (CUSMSTP) INTO (CUSTOMER_MASTER) PR1I00870 880415 
13600 111 __ KEY(ORDER_DETAIL.CUST) OPTIONS(KEYSEARCH(EQUAL)) ; 880415 
13700 55 111 FA] SUBCTL1_RECORD OUTPUT = CUSTOMER_MASTER, BY NAME; 880415 
13800 PRI00880 880415 
13900 /* FILL THE SCREEN */ PRI00890 880415 
14000 © 56 111 EE) DO WHILE(D_LINNUM < TOTLIN); PRI00910 880415 
14100 57 11 2 SUB1_RECORD = ORDER_DETAIL, BY NAME; 880415 
14200 «58 112 FR] = WRITE FILE (ORD220D) FROM (SUB1_RECORD) PR100948 880415 
14300 112 KEYFROM(D_LINNUM) OPTIONS(RECORD('SUB1')); PR190950 880415 
14400 «= 59 112 D_LINNUM = D_LINNUM + 1; 880415 
14500 60 1 1 2 READ_CHK = 'READ2'; 880415 
, 14600 = 61 112 READ FILE (ORDDTLP) INTO (ORDER_DETAIL) KEY(DETAIL_KEY) 880415 
14708 112 OPTIONS (KEYSEARCH(EQUAL)) ; 880415 
14800 © 62 112 END; /* DO WHILE */ 880415 
14900 880415 
15908 «= G3 111 SUB1_RECORD = ORDER_DETAIL, BY NAME; 880415 
15100 = 64 111 PZ) WRITE FILE (ORD220D) FROM (SUB1_RECORD) PRIQ@940 880415 
15200 111 KEYFROM(D_LINNUM) OPTIONS(RECORD('SUB1')) ; PR1@0950 880415 
1530865 111 SUB: IN57 = ON; 880415 
15408 = 66 111 STSOPN = OPNSTAT (DECIMAL (OPNSTS)) ; 880415 
15500 67 i 4-4 STSORD = ORDSTAT(DECIMAL(ORDSTS)) ; 880415 
15600 68 111 WRITE FILE (ORD220D) FROM (SUBCTL1_RECORD_OUTPUT) 886415 
15700 1 11 OPTIONS(RECORD('SUBCTL1') INDICATORS(SUBCTL1_INDICATORS)); 880415 
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Include SEQNBR STMT.SUBS BLK BN DO al rere Corr Peery ee, Peer Pee eee 
15860 69 111 IN57 = OFF; 
15900 70 111 INS8 = ON; 
16608 71 111 END; /* DO WHILE */ 
16168 
16260 72 1 1 CLOSE 
16368 11 FILE (ORD220D); 
16460 73 1 1 CLOSE 
16508 11 FILE (ORDHORP); 
16600 74 1 1 CLOSE 
16760 1 1 FILE (ORDDTLP); 
16860 75 1 1 CLOSE 
16960 11 FILE (CUSMSTP); 
17066 
17100 76 1 1 END LP1422; 


PL/I Source Listing 
LP1422: PROCEDURE; 


LP1422/LP1422 
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Figure 8-12. Display Produced Using Supporting DDS for Subfiles 


EXISTING ORDER INQUIRY 


ORDER 12345 


EVANS, NICK 


DATE 88/06/14 123 LARKSONG AVE. 
CUST # 11111 NORTH YORK 


ITEM QTY 


11114 945 
22228 = 10 
33332 6 


ON 


BITS AND BYTES 
ODDS AND ENDS 
LOTS OF STUFF 


98238 
INVOICE 61461 


ITEM DESCRIPTION 


TOTAL $22,606 
STATUS 4-READY 
OPEN 2-CLOSED 


CUSTOMER ORDER A375836743 


SHIP VIA 
PRINTED DATE 88 


PRICE 
560.00 


10,00 
1.00 


A re See Per 


11/30/88 15:39:54 


60 
PRT 


RUSH 
/06/17 


Pn ae 


Page 8 
PRI60166 


HocccleMeoteveced Date 


886415 
886415 
PRI66976 880415 
880415 
PRI66986 880415 
PRIG6996 886415 
PRI81066 880415 
PRI61016 880415 
880415 
886415 
880415 
886415 
PRI€1620 880415 
PR161636 880415 


MTH 06 YEAR 88 


EXTENS ION 


30.00 
1.60 
60 


RECORD data transmission is used with ORD220D, ORDHDRP, 
ORDDTLP, and CUSMSTP. 


ORD220D is declared as SEQUENTIAL KEYED, so that its records can be 


processed either sequentially or randomly by key. One of its fields, 


SUBCTL_RECORD _INPUT.ORDER, is used as a key when other files are 


accessed. 


The UPDATE attribute and the INTERACTIVE option of the ENVIRON- 


MENT attribute are specified for ORD220D. Both READ and WRITE 


statements are allowed, in this case to provide prompt screens and read input 


which is entered on the work station screen. 
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ORDHDRP, ORDDTLP, and CUSMSTP are declared with the DIRECT 
attribute, because they are accessed non-sequentially. 


ORDHDRP, ORDDTLP, and CUSMSTP are used for INPUT only; no 
output is directed to the files by the program. 


ORDHDRP, ORDDTLP, and CUSMSTP are INDEXED; the files are 
processed using the keyed sequence access path. 


DESCRIBED indicates that external record format definitions are used in the 
program. 


SUB1_ RECORD consists of all the OUTPUT fields in record format SUB1 
of file ORD220D. 


SUBCTL1_RECORD _INPUT consists of all the INPUT fields in record 
format SUBCTLI of file ORD220D. 


SUBCTL1RECORD OUTPUT consists of all the OUTPUT fields in 
record format SUBCTLI of file ORD220D. 


SUBCTLI1_ INDICATORS consists of all the INDICATORS in record 
format SUBCTLI of file ORD220D. 


This on-unit runs when a KEY condition is raised for file ORDHDRP. 


This do-group runs if the KEY condition is raised with code 51, that is, if no 
record in ORDHDRP has the key that is specified in a data transmission 
statement accessing the file. 


The files are opened. The data transmission modes were specified as attri- 
butes in the file declaration; they could also have been specified here as 
options of the OPEN statement, but instead have been incorporated as com- 
ments. 


Running of the do-loop continues while indicator 99 is set to OFF. When 
the user presses F1, indicator 99 is set to ON, running of the do-loop ends, 
the files are closed, and program running ends. 


The prompt screen record is written to the display file. Record format 
SUBCTLI is used. SUBCTLI_INDICATORS, a structure defined earlier 
using a % INCLUDE directive, is passed to the display device. 


The input supplied by the user is read into SUBCTL]_ RECORD INPUT 
using record format SUBCTLI, and the device returns its indicators to 
SUBCTLI INDICATORS. 


The key supplied by the user, field ORDER of structure 
SUBCTL1RECORD_INPUT, is used to find and read a record from file 
ORDHDRP into ORDER HEADER. The OPTIONS option of the 
READ statement specifies that the target key must be equal to the specified 
key. 


The appropriate fields of ORDER HEADER are then placed in 
SUBCTL1 RECORD OUTPUT using a BY NAME assignment statement. 
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DETAIL_KEY is a structure consisting of the fields D ORDER and 
D_LINNUM. The key supplied by the user, field ORDER of structure 
SUBCTLI_ RECORD OUTPUT, is assigned to DORDER. D_LINNUM 
is assigned an initial value of 1. 


DETAIL _KEY is used to find and read into ORDER_DETAIL the first 
record in ORDDTLP with the order number specified by the user. 


The customer number from the order detail record just read in is used as the 
key to read into CUSTOMER MASTER the record from CUSMSTP con- 
taining information on the customer that placed the order. 


The fields from CUSTOMER MASTER that will be displayed on the work 
station screen are assigned to SUBCTL1 RECORD OUTPUT. 


The program enters a loop which reads in data using the key supplied by the 
user. A comparison with TOTLIN ensures that the loop ends when all 
records for that particular order have been read in from file ORDDTLP. 


An order line is written to the subfile. 


The new subfile is written to the device file ORD220D, and the order display 
appears on the work station screen. 
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Example of Using Indicators 


Using Externally Defined Indicators in a Separate Area: The following program 


uses indicators in a separate area. They are included in the program with the 
“INCLUDE directive. 


AS/400 DATA DESCRIPTION SPECIFICATIONS GX21-9001-0 UM 


TRY is. 
Ssr=lz Internationa! Business Machines «Number of sheats per pod ial 


pe eo See ee fewne | Tit | tt feaigoeeaneet: 
[Programmer | ee (ea i HP 


Functans 


a3 45 47 OF SO 5) 81 AS 84 OE De 87 OF OF 8 At OZ 62 05 BS 8 U7 we OO E73 94 7 8 TS 


NSA R 
PRINT 
FO3(99" END OF PROGRAM‘ } 
FOS(5S1 ‘DAILY REPORT’ 

D9 (52 ONT REPOR 


Shae eee 
Pett ttt UE TE 10 TO" DEPARTMENT NUMBER: °C 
Te 
Pett, LT tT tT ts | 20) 26 PRODUCE MONTHLY REPORTS' 
ae a ee SPARC ee 
-—_Ae_} ff tt 
ae ee ee ‘F5 = DAILY REPORT’ 
— | 26°F9 = MONTHLY REPORT 
Af Lt td BEB "F3 = END! 


Figure 8-13 (Part 1 of 3). Program Using Indicators in a Separate Area 
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5728PL1 R61 MOG 888715 PL/I Source Listing LP1423/LP1423 11/30/88 15:36:01 Page 2 J 
LP1423: PROCEDURE; SEP@6160 
Include SEQNBR STMT.SUBS BLK BN DO te ee ere See Pee, eee Pee Se eee ee ee eer eye Lemre oe re rere all A 
166 1 LP1423: PROCEDURE; SEPQ6168 830817 
200 SEPQ01786 
3098 /* FILE DECLARATIONS */ SEP00186 
400 2 11 DECLARE al SEP00190 
500 i ff DISPFILE FILE RECORD SEQUENTIAL UPDATE ENV(INTERACTIVE); SEP08208 838687 
600 SEP06210 
700 /* RECORD DECLARATIONS */ SEP00220 
800 3 1 #1 DECLARE SEP@6230 
900 11 1 DISPLAY_RECORD, SEPQ0240 
1000 %INCLUDE DISPFILE(FORMAT1, INPUT, , COMMA) ; SEP@0258 831012 
FORMAT1 + 100 [® wn nnn nnn nn nn 2-2-2 o-oo = 5 5 oe 5 5-2 +--+ == == x/ 
FORMAT + 200 /* DEVICE FILE: DISPFILE.LP1423 x/ 
FORMAT1 + 300 /* FILE CREATION DATE: 87/11/30 */ 
FORMAT1 + 400 /* RECORD FORMAT: FORMAT1 */ 
FORMAT1 + 500 /* RECORD FORMAT SEQUENCE ID: 1122F3EAAD919 x/ 
FORMAT 1 + 600 [® wo-n----- 2-2-2 2-2-2 --- 22 o-oo - $2 $2 += 5 oo - 5-2 = == -- === -- */ 
FORMAT1 + 780 /* INDICATORS FOR FORMAT FORMAT1 x/ 
FORMAT1 + 800 /* INDICATOR 91 x/ 
FORMAT 1 + 900 /* INDICATOR 51 DAILY REPORT x/ 
FORMAT1 + 1000 /* INDICATOR 52 MONTHLY REPORT x/ 
FORMAT + 1100 /* INDICATOR 99 END OF PROGRAM x/ 
FORMAT1 + 1200 [B® wwe nnn nnn nnn nn nn nn nnn nn nn nnn nee ne ne nn oo ee eee = === */ 
FORMAT1 + 1300 3.1 1 1 15 DEPTNO CHAR(5), 
1100 3.2 11 1 INDICATOR_RECORD, SEPG0260 
1200 5 %S INCLUDE DISPFILE(FORMAT1, INDICATORS); SEPQ0270 830607 
FORMAT1 + 100 [Benne nnn nnn nnn nn nn nen nnn enn nn nn enn nn nn nn nnn ee nee en nee =e x/ 
FORMAT 1 + 200 /* DEVICE FILE: DISPFILE.LP1423 a} 
FORMAT1 + 300 /* FILE CREATION DATE: 87/11/30 */ 
FORMAT1 + 400 /*® RECORD FORMAT: FORMAT1 x/ 
FORMAT1 + 500 /* RECORD FORMAT SEQUENCE ID: 1122F3EAAD919 xf 
FORMAT 1 + 600 [® -2-n nn nnn nnn o-oo no eo + oo oe oe oe oe = 2 == === === xf 
FORMAT 1 + 700 3.0 11 15 ING] PIC ‘9', ) 
FORMAT1 + 800 3.4 11 15 INO2_IN50 CHAR(49), /* UNDEFINED INDICATOR(S) xf 
FORMAT1 + 906 3.5 11 15 IN5] PIC ‘9', /* DAILY REPORT x/ 
FORMAT1 + 1006 3.6 1 1 15 IN52 PIC '9', /* MONTHLY REPORT */ 
FORMAT1 + 1100 3.7 Ly A 15 IN53_IN98 CHAR(46), /* UNDEFINED INDICATOR(S) */ 
FORMAT1 + 1200 3.8 1 1 15 IN99 PIC '9'; /* END OF PROGRAM x/ 
1300 830607 
1400 /* SAMPLE SUBROUTINE DECLARATIONS */ 830607 
1500 4 1 1 DECLARE 830607 
1600 1 1 DAILY EXTERNAL ENTRY (CHAR(5)), 830607 
1700 4.1 1 1 MONTHLY EXTERNAL ENTRY (CHAR(5)); 830607 
1800 SEPG0280 
1900 /* INDICATOR FLAGS */ SEPG0290 
2000 5 1 1 DECLARE SEP60300 
2106 1 1 1 INDICATOR_FLAGS STATIC, SEP00310 
2200 5.1 1 1 2 OFF PICTURE '9' INIT(Q), SEPQ0320 831012 
2300 5.2 1 1 2 ON PICTURE '9' INIT(1); SEP00330 831012 
2400 SEP003480 
2500 /* BUILT-IN FUNCTIONS */ SEP00350 
2600 6 11 DECLARE SEP00366 
2700 1 1 SUBSTR BUILTIN, 831013 
2800 6.1 1 1 DATE BUILTIN; SEP00370 


Figure 8-13 (Part 2 of 3). Program Using Indicators in a Separate Area 
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5260 
5300 
5400 
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6000 
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64006 
6500 
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PL/I Source Listing LP1423/LP1423 
LP1423: PROCEDURE; 
RE C)é nF ie Lis atiecedeieetes 


co | 


/* PROGRAM VARIABLES */ 
DECLARE 
TODAYS_DATE 
1 CURRENT DATE, 
2  CURR_YEAR 
2 CURR MONTH 
2 CURR_DAY 


/* MAIN PROGRAM */ 
TODAYS_DATE = DATE; 
CURR_YEAR = SUBSTR(TODAYS DATE, 


CHAR(6), 
CHAR(2), 


CHAR(2), 
CHAR (2); 


1,2); 


CURR_MONTH = SUBSTR(TODAYS DATE,3,2); 


CURR_DAY 
IN99 = OFF; 


= SUBSTR(TODAYS DATE, 


OPEN 
FILE (DISPFILE); /* UPDATE */ 
DO WHILE(IN99 = OFF); 


/* DISPLAY THE SCREEN */ 

INO] = OFF; 

IF CURR_DAY = '@1' THEN 
INO1 = ON; 


WRITE FILE (DISPFILE) FROM (DISPLAY_RECORD) 
OPTIONS (RECORD('FORMAT1') INDICATORS(INDICATOR_RECORD) ); 


/* READ AND PROCESS SCREEN */ 
INDICATOR_RECORD = OFF; 


READ FILE (DISPFILE) INTO (DISPLAY RECORD) 
OPTIONS (RECORD(*FORMAT1') INDICATORS(INDICATOR_RECORD) ); 


IF IN51 = ON THEN 
CALL DAILY(DEPTNO) ; 
ELSE 
IF IN52 = ON THEN 
CALL MONTHLY(DEPTNO) ; 
END; /* DO WHILE */ 


CLOSE 
FILE (DISPFILE); 


END LP1423; 


5,2); 


/* EXTERNAL PROCEDURE */ 
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/* EXTERNAL PROCEDURE */ 


Ois< 


Page 
SEP80160 


SEP68380 
SEP00396 
SEP00408 


SEP00410 
SEP00426 
SEP904390 
SEP60446 
SEP60458 
SEP00460 
SEP60500 


SEP60516 


SEP@0526 
SEP00530 
SEP00540 
SEP06550 
SEP00566 
SEP00576 
SEPQ0580 
SEPO0590 
SEP@0600 
SEP00616 
SEP00Q628 
SEP60630 
SEP00646 
SEPQ@0650 
SEPQ0660 
SEP00670 
SEP00680 
SEP00690 
SEP00700 
SEP08710 
SEP00720 
SEP00730 
SEP00740 
SEP00750 
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DEPARTMENT NUMBER: 12345 


F5 = DAILY REPORT FQ = MONTHLY REPORT Fl = END 


Figure 8-14. Display for Program Using Indicators in a Separate Area 


RECORD data transmission is used with DISPFILE. 
The SEQUENTIAL access method is used with DISPFILE. 


The data transmission mode is specified as UPDATE, because the file is used 
for both input and output. 


2 

3 | 

EJ] The ENVIRONMENT attribute is specified with the INTERACTIVE 
option: both READ and WRITE statements are processed. 


The %INCLUDE statement generates declarations for the INDICATORS 
specified in record format FORMAT1 of file DISPFILE. 


[J = DISPFILE is opened. The data transmission mode UPDATE is specified in 
the record declaration. It could also be specified here as an option of the 
OPEN statement. 


The program continues running as long as IN99 has a value of OFF, that is, 
until the user ends program running. 


The prompt screen is displayed by writing DISPLAY RECORD to 
DISPFILE. Record format FORMAT} is used and the indicators passed to 
the display device are those declared in INDICATOR RECORD. 


E] = The information provided by the user is read into DISPLAY _ RECORD 
from fille DISPFILE using record format FORMAT], and the values of the 
indicators in INDICATOR_RECORD are returned by the device. 


Depending on the values of IN51 and IN52, an appropriate external proce- 
dure is called. 
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PL/I Source Listing PLITST/LP1424 11/30/88 14:48:47 Page 
LP1424: PROCEDURE; PGM@8160 
Satish Latace stated heres eG diye tase drew STs eek Ouwae tase Oaias eee 
LP1424; PROCEDURE; PGM00168 
P6M00170 
/* FILE DECLARATIONS */ PGM00180 
DECLARE i PGM00190 
DISPFILE FILE RECORD SEQUENTIAL UPDATE ENV(INTERACTIVE); PGMe0200 
PGM90210 
/* RECORD DECLARATIONS */ PGM00220 
DECLARE PGN00230 
1 DISPLAY_RECORD, PGM00240 
%INCLUDE DISPFILE(FORMAT1, INPUT, ,COMMA); PGM00250 
DEVICE FILE: DISPFILE.DBLIB 
FILE CREATION DATE: 87/11/05 
RECORD FORMAT: FORMAT1 
RECORD FORMAT SEQUENCE ID: 1122F3EAAD919 
INDICATORS FOR FORMAT FORMAT1 
INDICATOR 61 
INDICATOR 51 DAILY REPORT 
INDICATOR 52 MONTHLY REPORT 
INDICATOR 99 END OF PROGRAM 
15 DEPTNO CHAR(5), 
1 INDICATOR_RECORD, PGMQ0260 
15 IND_NEW_MONTH PICTURE '9', /* INO] NEW MONTH */ PGM00270 
15 IN@2_IN50 CHAR(49), /* UNDEF INDICATORS */ PGMO0280 
15 IND DAILY PICTURE ‘9', /* IN51 DAILY REPRT */ PGM00290 
15 IND MONTHLY PICTURE '9', /* IN52 MONTHLY RPRT*/ PGMO0300 
15 IN53_IN98 CHAR(46), /* UNDEF INDICATORS */ PGMO0310 
15 IND EOJ PICTURE '9'; /* IN99 END OF JOB */ PGMQ0320 
/* SAMPLE SUBROUTINE DECLARATIONS */ 
DECLARE 
DAILY EXTERNAL ENTRY (CHAR(5)), 
MONTHLY EXTERNAL ENTRY (CHAR(5)); 
PGM00330 
/* INDICATOR FLAGS */ PGM00340 
DECLARE PGM00350 
1 INDICATOR_FLAGS STATIC, P6MG0360 
2 OFF PICTURE '9' INIT(O), PGM00370 
2 ON PICTURE '9' INIT(1); PGNH00380 
PGM00390 
/* BUILT-IN FUNCTIONS */ PGM00400 
DECLARE PGM00410 
SUBSTR BUILTIN, 
DATE BUILTIN; PGH00420 
PGM00430 
/* PROGRAM VARIABLES */ PGN00440 
DECLARE PGM004 58 
TODAYS DATE CHAR(6), 
1 CURRENT DATE, PGM00460 
2 CURR_YEAR CHAR(2), PGM00470 
2 CURR_MONTH CHAR(2), PamMeoasa 
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Program Using Program-Defined Indicators in a Separate Area: The following 
program defines the same DDS as the above example using a separate indicator area. 
The indicators in this example are program-described. 
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Date 
830817 


830607 


831012 


830607 
830607 
830607 
830607 
830607 


831012 
831012 


831013 
831013 


831013 
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LP1424: PROCEDURE; 


PLITST/LP1424 11/30/88 14:48:47 Page 3 


P6Ma0166 


Include SEQNBR STMT.SUBS BLK BN DO *<..4....Leceeteee Qeccetec cs Sec cetececbansstecesSeccctecesOocsetesceTePeeteee08 Date 
4108 7.4 11 2 CURR_DAY CHAR(2); PGMaG496 
4200 P6Me0500 
4300 /* MAIN PROGRAM */ PGMe0510 
4490s 1 1  § OPEN P6Me0520 
4500 1 1 FILE (DISPFILE); /* UPDATE */ P6M00530 830919 
4600 P6moe540 
47009 11 TODAYS _DATE = DATE; P6M@0550 831013 
4g08 = «10 1 1 CURR_YEAR = SUBSTR(TODAYS DATE,1,2); 831013 
4900s 11 1 1 CURR_MONTH = SUBSTR(TODAYS DATE,3, 2); 831013 
5008 «= 12 11 CURR_DAY = SUBSTR(TODAYS DATE,5,2); 831013 
510013 11 IND_EOJ = OFF; P6M00560 
5200 = 14 1 1  & DO WHILE(IND_EOJ = OFF); PGM00570 830608 
5300 PGMo0580 
5400 /* DISPLAY THE SCREEN */ P6M00590 
5500 15 111 INDICATOR_RECORD = OFF; PGMa06e0 
5608 «= 16 111 IF CURR_DAY = '@1' THEN PGM00610 
5700 Le ard IND_NEW_MONTH = ON; PGM00620 
5800 = 17 11186 WRITE FILE (DISPFILE) FROM (DISPLAY_RECORD) PGM00630 830607 
5900 111 OPTIONS (RECORD('FORMAT1') INDICATORS(INDICATOR_RECORD));  PGM00646 831013 
6000 PGM00650 
6160 /* READ AND PROCESS SCREEN */ PGMOQ660 
6200 18 1141 § READ FILE (DISPFILE) INTO (DISPLAY_RECORD) PGM00678 830607 
6300 111 OPTIONS (RECORD(*FORMAT1') INDICATORS(INDICATOR_RECORD)) ; PGMe0680 831013 
6400 «=:19 1 1 1 FQ IF IND_DAILY = ON THEN PG600690 
6500 111 CALL DAILY(DEPTNO) ; PGM00700 
6600 = 20 111 6 ELSE P6M0e710 
6700 111 IF IND_MONTHLY = ON THEN P6Me0720 
6800 111 CALL MONTHLY (DEPTNO) ; PGH00730 
6900 = 21 111 END; /* DO WHILE */ P6moo740 
7000 PGM00750 , 
7106 = 22 i, CLOSE PGM00760 j 
7200 11 FILE (DISPFILE); PGM00770 830607 
7300 PGM90780 
7400 © 23 11 END LP1424; PGM0079@ 830817 


Figure 8-15 (Part 2 of 2). Program Using Program-Defined Indicators in a Separate Area 


RECORD data transmission 1s used with DISPFILE. 
The SEQUENTIAL access method is used with DISPFILE. 


The data transmission mode is specified as UPDATE, because the file is used 
for both input and output. 


The ENVIRONMENT attribute is specified with the INTERACTIVE 
option: both READ and WRITE statements are processed. 


mo 


Gg 


The %INCLUDE statement is not used to generate declarations for the indi- 
cators. Instead, the indicators are program-defined. This has the advantage 
that you can give the indicators meaningful variable names. It has the disad- 
vantage that you must ensure that you have coded the indicators correctly. 
The %INCLUDE statement generates declarations for the INPUT fields 
specified in record format FORMAT of file DISPFILE. 


[fi DISPFILE is opened. The data transmission mode UPDATE is specified in 
the record declaration. It could also be specified here as an option of the 
OPEN statement. 


The program continues running as long as IND_EOJ has a value of OFF, 
that is, until the user ends program running. 


J 
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FE] = The prompt screen is displayed by writing DISPLAY RECORD to 
DISPFILE. Record format FORMAT is used and the indicators passed to 
the display device are those declared in INDICATOR_RECORD. 


E] = The information provided by the user is read into DISPLAY RECORD 
from file DISPFILE using record format FORMAT], and the values of the 
indicators in INDICATOR_RECORD are returned by the device. 


Depending on the values of IND DAILY and IND MONTHLY an appro- 
priate external procedure 1s called. 


Using Indicators in the Record Area: You can also use indicators that are 
included in your record area. To do this, you must specify NOINDARA as an 
option in the ENVIRONMENT attribute of the file declaration. You can even use 
% INCLUDE to include the indicators, but they will not be in a separate area. This 
method of using indicators 1s not recommended. It is available in AS/400 PL/I to 
ensure compatibility if you are translating a program written in another AS/400 lan- 


guage. 


When using indicators in the record buffer you must take into consideration the fact 
that the indicators may not be in ascending sequential order. The indicators are 
located in the buffer in the order in which they are declared in the DDs source for 
the file. For example, if indicator 97 is the first indicator declared in the DDs for the 
file, it will also be the first in order in the buffer. 


If you are using externally described record definitions, the %oINCLUDE directive 
will list the indicators according to their order in the input/output buffers. If the 
record definitions are program-described, you must ensure that the order in which 
you list the indicators is the same as the order they have in the buffer. If you fail to 
do this, there may be a mismatch between the indicators set on in the program and 
the indicators set on in the file description. 


Using Device Files 


Although the different types of device files (Communications, BSC, Printer, Inline, 
Tape, and Diskette) have some differences between them, there are also some simi- 
larities. Most importantly, they all support the combination of CONSECUTIVE 
organization and SEQUENTIAL access. This is to increase device independence 
and allow for file redirection. With Communications and Bsc files, INTERAC- 
TIVE organization is also allowed. The input/output statements allowed with each 
file type are shown in Appendix C, ‘Valid Combinations of Options for 
Input/Output Statements.” 


Other ENVIRONMENT options which can be specified for device files are 
BUFSIZE, which can be specified for any type of file; BLOCK, which is valid for 
Tape and Diskette files only; and NOINDARA, which can be specified for Com- 
munications, BSC, and Printer files. All of these are discussed in Chapter 7, ‘File 
Declaration and Input/Output.” 


For TAPE files with variable length records or undefined records, the length of the 
variable on the WRITE statement determines the length of the tape record. 
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Externally Described Device Files 
Communications, BSC, display and printer files are the only device files that can be 
externally described. For these files, you can specify the DESCRIBED option, as 
discussed in Chapter 7, “File Declaration and Input/Output.” 


Program-Described Device Files 
All types of device files can be program-described. Ifa printer file is program- 
described, then you have the option of using the CTLASA option, described in 
Chapter 7, “File Declaration and Input/Output.” 


Example of Using a Printer File 
The following program and supporting DDs uses a printer file to create a report. 


TY AS/400 DATA DESCRIPTION SPECIFICATIONS ora-2001-0 as 


International Business Machines tNumber af shests per pad may vary slightly. 


= Ee 
ecru i HE GS OY 


TEXT(”° HOME ADDRESS) 

TEXT(* SPOUSE WORK ADDRESS") 
TEXTC DATE OF BIRTH') 
HATS TAT al TEXT( MARITAL STATUS’ 
SPOUSENAME | 28 | | | TEXTC*NAME OF SPOUSE’) 
A ea BE TEXT(°NUMBER OF CHILDREN’) 


|__A FOR, PERSONNE — 
:. 
| CUA OT ORT PERSREC | 
A ewe tas tree ‘EMPLOYEE NUMBER’ ) 
ae ae LT [] TTNAME | | TT) 28] TEXT( EMPLOYEE NAME’) 
{Taporess2 "3st 


feed 

AL] | Ht i aera A a ee Ee 
"A 0 ee ee 
7 Ge a na 


Figure 8-16 (Part 1 of 6). Program Using Printer File and Supporting DDS 
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TRH AS/400 DATA DESCRIPTION SPECIFICATIONS X21-9891-0 UM/Ct0» 
S=aar=%= International Business Mochines viiceco aS unceaes es edb U.S.A. 


= 
a 


hl MaMa DO ee As ie As 


[We| PRINTER FILE DDS FOR PERSONNEL FILE] 
LA a TENDARA_ REF CPERSFILE) 

PAT TT TT UR) HEADING | {Ut UT CSKEPBC1) SPACEACS) 
| TTT TT tT PT PERSONNEL LISTING! 

ee PN) Me Le EE 2 SUNDER IN re 
PAL TT ? - ORDERED BY 

PUTT OT TT TL GRDERTYPE || SST 
LA  BODATE EDTCDECY) 

ean NN a I eo N eel ee ae 18! PAGED UME 
PAGNBR EDTCDE(3) 


Ada 
aa Oe eee : UNDERLINE 
A IRONS EMPLOYEE NUMBER: CH + 
TT eR 
ae Sine eae eee eae a7°0ATE OF BIRTH:* cs 


LAL LL IBIRTHDATIE IRL | TT OSSPACEACT) OO =F CCH 
( Figure 8-16 (Part 2 of 6). Program Using Printer File and Supporting DDS 
Tr . AS/400 DATA DESCRIPTION SPECIFICATIONS aoe printed In USA, 


= International Business Machines #Number af ahoets per pad may wary slightly. 


=a sii 
a a eee | 


82 3) As 88 50 57 8S OF FG a} Ol OF Bt Bo OA C7 OM 7D 71 72 73-74 8 eT 


| 

3 eet 

| ADDRESS2 RO || | 

| CUA PEt ie ee See 5 

POAT NUMcHILD IRC 

as Ee ee ee eee ee eee ee ee 

--- HE —- - | —1. -+ - 
ik i 
2h eas Te Ee 5 ae ee 


1 


C ee 


Figure 8-16 (Part 3 of 6). Program Using Printer File and Supporting DDS 
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5728PL1 RO1 MOG 880715 PL/I Source Listing QTEMP/LP1421 11/30/88 15:37:16 Page 2 
LP1421: PROCEDURE; . PRI@6166 
Include SEQNBR STMT.SUBS BLK BN DO *<..4....]e cc etec ee Zecsete ccc Se nc etene Ae cectecccDeccctececOeccctecceTPeetess e8 Date 
100 1 LP1421: PROCEDURE; PRI86160 830817 
200 PRI60170 
300 /* FILE DECLARATIONS */ PRIG@180 
400 2 1 1 DECLARE fl 2] 3 4 g PRI00190 
500 11 PERSFILE FILE RECORD SEQUENTIAL INPUT ENV(INDEXED DESCRIBED), PR1ee208 830919 
600 2.1 11 PERSREPT FILE RECORD SEQUENTIAL OUTPUT ENV(CONSECUTIVE DESCRIBED); PR100216 840301 
700 7 fi PRI00226 
800 /* RECORD DECLARATIONS */ PRI60230 
900 3 11 DECLARE PRI00246 
1000 11 1 PERSFILE_RECORD, PR196250 
1100 %INCLUDE PERSFILE(PERSREC,RECORD, ,COMMA) ; PRIG0268 830919 
PERSREC + 100 [® won en nnn n nn nn non on enon 2 nnn nnn nn nen ne nn ene n nn eee == */ 
PERSREC + 200 /* PHYSICAL FILE: PERSFILE.QTEMP */ 
PERSREC + 300 /* FILE CREATION DATE: 87/11/30 */ 
PERSREC + 400 /* RECORD FORMAT: PERSREC */ 
PERSREC + 500 /* RECORD FORMAT SEQUENCE ID: 58986345F0578 */ 
PERSREC + 600 ee */ 
PERSREC + 700 3.1 11 15 EMPLNO PIC '99999R', §/* EMPLOYEE NUMBER */ 
PERSREC + 800 /* DDS - KEY FIELD */ 
PERSREC + 900 3.2 11 15 NAME CHAR(28), /* EMPLOYEE NAME */ 
PERSREC + 1000 3.3 11 15 ADDRESS1 CHAR(35), /* HOME ADDRESS */ 
PERSREC + 1100 3.4 1: 15 ADDRESS2 CHAR(35), /* SPOUSE WORK ADDRESS */ 
PERSREC + 1200 3.5 1 1 15 BIRTHDATE CHAR(6), /* DATE OF BIRTH */ 
PERSREC + 1300 3.6 11 15 MARSTAT —CHAR(1), /* MARITAL STATUS */ 
PERSREC + 1400 3.7 11 15 SPOUSENAME CHAR(28), /* NAME OF SPOUSE */ 
PERSREC + 1500 3.8 11 15 NUMCHILD PIC '9R', /* NUMBER OF CHILDREN */ 
1200 = 3.9 11 1 HEADING OUTPUT, PRI60276 
1300 %INCLUDE PERSREPT(HEADING, OUTPUT, , COMMA) ; PR100280 831006 
HEADING + 100 [* ---2------------------------ +--+ ----- +--+ 2 -- 22-2 +--+ */ 
HEADING + 200 /* DEVICE FILE: PERSREPT.QTEMP */ 
HEADING + 300 /* FILE CREATION DATE: 87/11/30 */ 
HEADING + 400 /* RECORD FORMAT: HEADING */ 
HEADING + 500 /* RECORD FORMAT SEQUENCE ID: 1450B069F8720 */ 
HEADING + 600 [® w2cnn nnn -- 22222 -- 22 --- 2 == + nn no enone nee */ 
HEADING + 700 3.10 1 1 15 ORDERTYPE CHAR(33), 
14000 3.11 UA 1 DETAIL_OUTPUT, PR100290 
1500 %INCLUDE PERSREPT (DETAIL, OUTPUT, , COMMA) ; PRI00300 831006 
DETAIL + 100 [® 2-222 nne-- 222 - on enn ene nnn enon ne ne nee ene een e ene --e */ 
DETAIL + 200 /* DEVICE FILE: PERSREPT.QTEMP */ 
DETAIL + 300 /* FILE CREATION DATE: 87/11/30 */ 
DETAIL + 400 /* RECORD FORMAT: DETAIL */ 
DETAIL + 500 /* RECORD FORMAT SEQUENCE ID: 1EC226084A40B */ 
DETAIL + 600 PR Be eee a oe ae en eee ees eee */ 
DETAIL + 700 /* INDICATORS FOR FORMAT DETAIL */ 
DETAIL + 800 /* INDICATOR @1 */ 
DETAIL + 900 [® wenn nnn n-nonane wenn nen een nn ne ne nnn eee nee nee ene ene n nee e- */ 
DETAIL + 1000 3.12 1 1 15 NAME CHAR(28) , /* EMPLOYEE NAME x/ 
DETAIL + 1100 3.13 11 15 EMPLNO PIC '99999R', §/* EMPLOYEE NUMBER */ 
DETAIL + 1200 3.14 1 1 15 BIRTHDATE CHAR(6), /* DATE OF BIRTH */ 
DETAIL + 1300 3.15 11 15 ADDRESS1 CHAR(35), /* HOME ADDRESS */ 
DETAIL + 1400 3.16 11 15 MARSTAT = CHAR(1), /* MARITAL STATUS */ 
DETAIL + 1500 3.17 11 15 SPOUSENAME CHAR(28), /* NAME OF SPOUSE */ 
DETAIL + 1600 3.18 11 15 ADDRESS2 CHAR(35), /* SPOUSE WORK ADDRESS */ 


Figure 8-16 (Part 4 of 6). Program Using Printer File and Supporting DDS 
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5728PL1 R01 M08 880715 PL/I Source Listing QTEMP/LP1421 11/30/88 15:37:16 Page 3 
LP1421: PROCEDURE; PR100160 
Include SEQNBR STMT.SUBS BLK BN DO React exec loses teN en eee ease e Sewer case AN caed teas sO vant ecn5 Os cas eee a> oeteseee UAte 
DETAIL + 1700 3.19 1 1 15 NUMCHILD PIC ‘OR’, /* NUMBER OF CHILDREN */ 
1608 3.20 11 1 PERSREPT_INDICATORS, PRI00310 
1760 % INCLUDE PERSREPT (DETAIL, INDICATORS) ; PR100320 
DETAIL + 100 [® wenn nnn nnn nn nnn nn nnn n nn nn nnn nnn neon nee nn nee enn ne eon o eee */ 
DETAIL + 200 /* DEVICE FILE: PERSREPT.QTEMP */ 
DETAIL + 306 /* FILE CREATION DATE: 87/11/30 */ 
DETAIL + 400 /* RECORD FORMAT: DETAIL */ 
DETAIL + 500 /* RECORD FORMAT SEQUENCE ID: 1£C226084A4DB */ 
DETAIL + 600 [® wwen nnn nn nnn anno nn nnn nn nnn neon nnn nnn nn en nnn one enn ee eee eee */ 
DETAIL + 700 3.21 a 15 INO1 PIC '9', 
DETAIL + 806 3.22 1 1 15 IN62_IN99 CHAR(98); /* UNDEFINED INDICATOR(S) */ 
1800 PR160330 
1900 /* INDICATOR FLAGS */ PR100340 
20004 1 1 DECLARE PR100350 
2106 1 1 1 INDICATOR_FLAGS STATIC, PR160360 
22002 4.1 1 1 2 OFF PICTURE '9' INIT(@), PRI00370 831006 
2300 «4.2 1 1 2 ON PICTURE '9' INIT(1); PR160380 831006 
2400 PR100390 
2500 /* PROGRAM FLAGS */ PR100400 
2600 «5 1 1 DECLARE PRI00416 
2700 1 1 1 BIT_FLAGS STATIC, PR100420 
2800 Ss«5. 1 1 1 2 MORE_RECORDS BIT(1) ALIGNED, PRI00430 
2900 = «5.2 1 1 2 NO BIT(1) ALIGNED INIT(‘@'B), PR100440 
3000S s«5.3 1 1 2 YES BIT(1) ALIGNED INIT(‘1'B); PR100450 
3100 PR100460 
3200 /* STATIC VARIABLES */ PR1I00470 
3300S s«G 1 1 DECLARE PRI00486 
3400 11 1 STATIC_VARIABLES STATIC, PRI00496 
3500 6.1 1 1 2 HEAD_FMT CHAR(10) INIT('HEADING'), PRIaG500 
3600 = «6.2 11 2 HEAD_ORDER CHAR(15) INIT('EMPLOYEE NUMBER'), PRI00520 
‘ 37008 =—s«6.3 1 1 2 DETAIL_FMT CHAR(10) INIT('DETAIL'), PR160530 
3800 = «6.4 1 1 2 DETAIL_LINES BINARY FIXED(5) INIT(5), PRI00540 831006 
3900 = «6.5 1 1 2 MARRIED CHAR(1) INIT('M'), PR1I00550 
4000 6.6 1 1 2 PAGE_SIZE BINARY FIXED(7) INIT(50); PRI00560 831006 
4100 PRI00576 
4200 /* PROGRAM VARIABLES */ PR100580 
43007 11 DECLARE PRI00590 
4400 11 LINE_COUNT BINARY FIXED(5); PRI80600 831007 
4500 PR100610 
4600 Ss 8 11 ON ENDFILE(PERSFILE) PR100620 
4700 11 MORE_RECORDS = NO; PRI00630 
4800 PR100640 
| 4900 /* MAIN PROGRAM */ PRI60650 
50009 11 MORE_RECORDS = YES; PRI00660 
| 5100 PRI00680 
5200 ©: 10 1 1 [FR open PR100690 
5300 1 1 FILE (PERSFILE); /* INPUT */ PRI00700 830919 
5400 11 1 1 ([W@  open PRI00710 
5500 11 FILE (PERSREPT); /* OUTPUT */ PRI00720 830919 
5600 PRI00730 
5700 = 12 1 1 READ FILE (PERSFILE) INTO (PERSFILE_RECORD) ; PRI00740 831007 
5800 PR1I00750 
5900 «13 11 DO WHILE(MORE_RECORDS) ; PRI00760 


Figure 8-16 (Part 5 of 6). Program Using Printer File and Supporting DDS 
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5728PL1 RG1 MGO 886715 


Include SEQNBR STMT.SUBS BLK 
6000 
6100 14 1 
6200 15 1 
6300 1 
6400 
6500 16 1 
6600 17 1 
6700 18 L 
6860 1 
6900 19 1 
7000 1 
7100 
7200 20 1 
7300 1 
7400 21 1 
7506 22 1 
7600 23 1 
7708 1 
7800 24 1 
7908 
8000 25 1 
8100 
8200 26 1 
8300 1 
8400 27 1 
8500 1 
8600 
8700 28 1 


PL/I Source Listing QTEMP/LP1421 11/36/88 15:37:16 
LP1421: PROCEDURE; 


Page 4 
PRI00160 


BN DO Be St bee Lean he aad Cie Pas oc Ouse wt Rea See on Dee wets ew Oe cece ae lec P cance Date 


ry 


= — eS 


1 


1 ORDERTYPE = HEAD_ORDER; 
1 14] WRITE FILE (PERSREPT) FROM (HEADING_OUTPUT) 
1 OPTIONS (RECORD('HEADING')); 


1 DO LINE COUNT = 1 TO PAGE_SIZE; 

2 DETAIL_OUTPUT = PERSFILE_RECORD, BY NAME; 
2 IF PERSFILE_RECORD.MARSTAT = MARRIED THEN 
2 INO1 = ON; 

2 ELSE 

2 INQ1 = OFF; 


2 12 WRITE FILE (PERSREPT) FROM (DETAIL_OUTPUT) 
2 OPTIONS(RECORD('DETAIL') INDICATORS(PERSREPT_INDICATORS)); 
2 LINE_COUNT = LINE_COUNT + DETAIL_LINES; 
2 READ FILE (PERSFILE) INTO (PERSFILE_RECORD) ; 
2 IF =MORE_RECORDS THEN 
2 LINE_COUNT = PAGE SIZE + 1; 
2 END; /* DO */ 
1 END; /* DO WHILE */ 

CLOSE 

FILE (PERSFILE); 
CLOSE 


FILE (PERSREPT) ; 


END LP1421; 


Figure 8-16 (Part 6 of 6). Program Using Printer File and Supporting DDS 


RECORD data transmission 1s used with PERSFILE. 
The SEQUENTIAL access method is used with PERSFILE. 
PERSFILE is used for INPUT only; no data is directed to it. 


PRI90776 
PRI80860 830919 
PRI9G810 830919 
PRIQ0820 831007 
PR100858 
831007 
PRIG0868 830919 
PRI60876 830919 
PRIO0880 830919 
PRIG0890 830919 
PRI00900 830919 
PRI00910 
PRI00920 830919 
PRI00930 831007 
PRI00948 830919 
PRI90950 831007 
831007 
830919 
830919 
830919 
PRIO0960 
PRI00970 
PRI90980 
PRI 00990 
PRIO1000 
PRIG1010 
PRI01020 
PRIQ1030 830817 


INDEXED specifies that PERSFILE is processed using the keyed sequence 


access path. 


DESCRIBED specifies that the % INCLUDE directive is used to bring 
external record format definitions from PERSFILE into the program. The 
DESCRIBED option ensures that at the time of program compilation the 
PL/I file attributes match the system file attributes, and that level checking is 


processed when the file is opened during program running. 
RECORD data transmission is used with PERSREPT. 
The SEQUENTIAL access method is used with PERSREPT. 


PERSREPT is used for OUTPUT only. It does not provide data to the 


program. 


The CONSECUTIVE option specifies that the file is processed using the 
arrival sequence access path. Because CONSECUTIVE is the default, the 


CONSECUTIVE option could have been omitted. 


PERSFILE and PERSREPT are opened. Their data transmission modes 


(INPUT and OUTPUT) are omitted here, because they are included as attri- 


butes in the file declaration. 
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( The first line printed on each page is the heading. The first WRITE state- 
ment writes record HEADING OUTPUT to file PERSREPT using record 
format HEADING. 


Record DETAIL OUTPUT is written to PERSREPT using record format 
DETAIL. 


The indicators in PERSREPT_INDICATORS are passed to the printer. 


Using STREAM Files 


Stream files are a type of program-described file. They can be connected only to 
files that do not have record definitions. They are file-independent because they can 
only be used for arrival sequence access. 
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Example of Using a Stream File 


5728PL1 R@1 M06 889715 


Include 


SEQNBR STMT.SUBS BLK BN DO 
108 1 
208 
306 
460 2 1 
500 1 
600 2.1 1 
760 
800 
900 3 
1000 
1100 3 
1200 3. 
3 
3 


— - pe 


1300 

1400 

1500 

1600 

1700 4 
1806 

1900 4.1 
2008 4.2 
2100 4.3 
2200 

2300 

2400 5 
2500 

2600 5 
2708 5. 
2800 5 
2900 

3000 6 
3160 

3200 

3308 7 
3400 

3508 8 
3600 

3700 9 
3800 

3900 160 
4000 

4100 

4200 

4308 11 
4400 12 
4500 

4600 

4706 13 1 
4800 14 1 1 
4900 

5600 15 1 1 
5100 11 
5200 

5300 16 1 il 


ee ee ee ee ee) 
— — — — 


— — — — 
— — — — 


= ee 
Mm MO MH MP PY PM MD PD PY P Fe F* — — — — — 


WWWWWWwNwwwwne 
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PL/I Source Listing 
LP1418: PROCEDURE; 
RE Heck Feet clescs 


LP1418; PROCEDURE; 


/* FILE DECLARATIONS */ 
DECLARE il 2 


PLITST/LP1418 


EMP_FILE FILE STREAM INPUT, 
SYSPRINT FILE STREAM OUTPUT PRINT; 


/* VARIABLE DECLARATIONS 
DECLARE 
EMP_NUMBER 
EMP_NAME 
EMP_RATE 
EMP_HOURS 
EMP_DEDUCTIONS 


/* PROGRAM FLAGS */ 
DECLARE 


1 BIT_FLAGS STATIC, 
2 MORE_RECORDS 
2 NO 
2 YES 


/* PROGRAM VARIABLES */ 
DECLARE 

GROSS PAY 

NET_PAY 

OVERTIME 

PAGE_NUMBER 


ON ENDFILE(EMP_FILE) 
MORE_RECORDS = NO; 


ON ENDPAGE (SYSPRINT) 
BEGIN; 


of 


CHAR(6), 
CHAR(28) 
DECIMAL 
DECIMAL 
DECIMAL 


BIT(1) 
BIT(1) 
BIT(1) 


DECIMAL 
DECIMAL 
DECIMAL 


11/36/88 14:21:11 


FIXED(5,2), 
FIXED(4,1), 
FIXED (6,2); 


ALIGNED, 
ALIGNED 
ALIGNED 


INIT(‘'8'B), 
INIT(‘'1'B); 


FIXED(7,2), 
FIXED(7,2), 
FIXED(4,1), 


BINARY FIXED(2); 


PUT FILE (SYSPRINT) PAGE EDIT(‘PAGE 


(X(81), 


", PAGE_NUMBER) 
A(6),F(2)); 


PUT FILE (SYSPRINT) SKIP(3) EDIT('EMPLOYEE PAYROLL ') 

(X(38) ,A(16)); 

PUT FILE (SYSPRINT) SKIP(2) EDIT('EMPLY#', EMPLOYEE NAME’, 'RATE' ,STROQ546 
"REG HRS', ‘OVERTME', 'GROSS PAY', ‘DEDUCTIONS’, ‘NET PAY') 
(A(6) .X(6),A(13) .X(5) A(4) X(2) .A(7) 0X(2) A(7) .X(2) .A(9) » 


X(2),A(16) ,X(2),A(7)); 


PAGE_NUMBER * PAGE_NUMBER + 1; 


END; /* BEGIN */ 


/* MAIN PROGRAM */ 
PAGE_NUMBER = 1; 
MORE_RECORDS = YES; 


OPEN 


FILE (EMP_FILE) TITLE('EMPFILE'); /* INPUT */ 


SIGNAL ENDPAGE (SYSPRINT) 


Figure 8-17 (Part 1 of 2). Program Using Stream I/O 
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STRO6166 


Pos od Decca Veta s Owe ee Wee cnd oP ietewese Date 


STRO6168 836817 
STRO0176 
STROO0186 
STRO01960 
STRO6200 
STR60216 
STR66220 
STROO230 
STROG240 
STROO258 831004 
STRO6260 
STROG270 831604 
STRO6288 831604 
STRO6298 831664 
STROG300 
STRO6316 
STRO0320 
STR60330 
STROO340 
STROO356 
STROQ360 
STR06370 
STRO0380 
STRO6396 
STRO6460 
STROO410 
STR60426 831664 
STRO6436 
STRO0446 
STRO0450 
STRO0460 
STRO6476 
STRO0486 
STR604 90 
STR66500 
STRO6516 
STR60526 
STRO0536 


STR60556 
STRO0566 
S$TRO0576 
STROG586 
STROG596 
STROO600 
STRO0610 
STRO0626 
STRO0636 
STRO0646 
STRO0650 
STRO6668 836919 
STRO0670 
STROO680 


C 


C 
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5728PL1 RB1 M68 880715 PL/I Source Listing PLITST/LP1418 11/30/88 14:21:11 Page 3 

LP1418: PROCEDURE; STROG160 
Include SEQNBR STMT.SUBS BLK BN DO *<..4.... Lic ctecee Que cote c cc Secc ete eecdescetecccSeeretecscDeccetenceTerPecteee eB Date 

5408017 1 1 GET FILE (EMP_FILE) EDIT(EMP_NUMBER,EMP_NAME,EMP_RATE,EMP_HOURS,  ‘ STROG690 

5500 11 EMP_DEDUCTIONS) (A(6) ,A(20) ,F(5,2),F(4,1),F(6,2)); STROQ7OO 831004 
5600 STROO710 
5700 «18 11 DO WHILE (MORE_RECORDS) ; STROO720 
5800 «19 111 GROSS PAY = 0.0; STROO730 
5908 = _28 111 NET PAY = 0.0; STROO740 
6000 = 21 111 OVERTIME = 0.0; STROO750 
6100 = 22 111 IF EMP_HOURS > 48.0 THEN STROQ760 
6200 111 DO; STROO770 
6300 © 23 112 OVERTIME = EMP_HOURS - 40.0; STROO780 
6400 = 24 112 EMP_HOURS = 40.0; STROO790 
6508 = 25 1 12 GROSS PAY = OVERTIME * (1.5 * EMP RATE); STROO8OO 
6600 26 112 END; STROO810 
6700 = 27 111 GROSS PAY = GROSS PAY + (EMP_HOURS * EMP RATE); STROO820 
6800 ©. 28 111 NET_PAY = GROSS PAY - EMP_DEDUCTIONS; STROO830 
6900 © 29 111 PUT FILE (SYSPRINT) SKIP EDIT(EMP_NUMBER,EMP_NAME,EMP_RATE, STROO84G 
7000 111 EMP_HOURS, OVERTIME, GROSS_PAY,EMP_DEDUCTIONS,NET_PAY) (A(6) ,X(2) ,STRO0850 

7108 111 A(20) ,F (6,2) .X(2),F (5,1) .X(4) 6F (5.1) .X(4) .F (8,2) .X(6), STROO8GO 831004 

7200 111 F(6,2),X(2),F(8,2)); STROG87A 831004 
7300 «(30 111 GET FILE (EMP_FILE) SKIP EDIT(EMP_NUMBER,EMP_NAME,EMP RATE, STROO88O 

7408 111 EMP_HOURS, EMP_DEDUCTIONS) (A(6) ,A(20) ,F(5,2),F(4,1),F(6,2));  STR@0890 831004 
7500 = 31 111 END; /* DO WHILE */ STROQ900 
7600 STROO910 
7708 © 32 1 1 CLOSE STRE0920 
7800 1 1 FILE (EMP_FILE); STROQ930 
790033 11 CLOSE STROOS4A 
8008 11 FILE (SYSPRINT) ; STROO95O 
8100 STROO960 

8200 34 11 END LP1418; STROO97O 830817 


Figure 8-17 (Part 2 of 2). Program Using Stream 1/O 


STREAM data transmission is used with EMP_FILE. 


EMP _FILE is used for INPUT only. No data is directed to it by the 
program. STREAM INPUT can be omitted for EMP_FILE, because these 
are the default attributes for file declarations. 


STREAM data transmission is used with SYSPRINT. 


SYSPRINT is used for OUTPUT only. It does not provide data to the 
program. 


The PRINT attribute specifies that the first character in each record is an 
ASA carriage control character. 


SYSPRINT is implicitly opened by the first processing of the PUT state- 
ment. Any file that is not explicitly opened is implicitly opened by the first 
data transmission statement that accesses it. It is, however, a good practice 
to explicitly open all your files. 


EMP FILE is explicitly opened. In the file declaration, INPUT has already 
been specified as an attribute of EMP_FILE. With both stream and record 
files, the data transmission mode can be specified in the file declaration, or in 
the OPEN statement, or in both places. If you specify the data transmission 
mode in both places, you must be sure that you specify the same mode both 
times. 
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FE} = The TITLE option is specified, with the parameter 'EMPFILE'. Because 
the library and member names are allowed to default, the first member of file 
EMPFILE in the library list is opened. 


E] A list of variables is written to SYSPRINT. The SKIP option is specified, 
but no parameter is supplied. The compiler supplies a default value of 1, so 
one line is skipped before the line is printed. 


Commitment Control 


Commitment control allows you to ensure that when a commitment boundary is 
reached, multiple changes to data base files are either made permanent or canceled, 
as a single operation. 


PL/I support for commitment control consists of the following: 


¢ COMMITTABLE option on the ENVIRONMENT file declaration attribute to 
indicate that a file should be placed under commitment control. 


¢ PLICOMMIT built-in procedure to complete changes to the data base. 
¢ PLIROLLBACK built-in procedure to cancel changes to the data base. 


The AS/400 System support for commitment control consists of the following: 


e The CL command STRCMTCL (Start Commitment Control) to start commit- 
ment control. It indicates that commitment control can be used, and establishes 
the record locking at either the high level («ALL) or the low level (*«CHG). 


— «ALL record locking is useful primarily to protect concurrent jobs from 
uncommitted changes. 


— «CHG record locking is useful primarily to simplify recovery. 


¢ The CL command ENDCMTCTL (End Commitment Control) ends commit- 
ment control. This command cancels any changes to the data base files that are 
under commitment control. 


For more information on commitment control, see the Programming: Control Lan- 
guage Programmer's Guide. For more information on the STRCMTCTL and 
ENDCMTCTL commands, refer to the Programming: Control Language 
Reference. 


PLICOMMIT and PLIROLLBACK are used to maintain a collection of one or 
more data base files in a consistent state. Changes made to data base files under 
commitment control are only completed when a PLICOMMIT is processed. Use 
the PLICOMMIT built-in subroutine to complete or commit all changes made 
through the WRITE, REWRITE, and DELETE statements, and the 
PLIROLLBACK built-in subroutine to remove or roll back any changes made by 
WRITE, REWRITE, and DELETE statements since the last PLICOMMIT or 
PLIROLLBACK. If a problem occurs during processing, the changes made since 
the last PLICOMMIT call can be removed by processing PLIROLLBACK. 
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If the commitment control environment is abnormally ended (either by a system or 
job failure), the system will ensure that any uncommitted changes are removed from 
the data base (an implicit rollback operation is processed). 


The commit and rollback operations may also be processed by statements in other 
high-level languages. Commit or rollback operations processed by any program of 
the job written in any language apply to all committable files that your PL/I program 
is using. This feature allows the user to keep data base files at consistent transaction 
boundaries. 


Using the COMMITTABLE Option 


The format for the commitment control option 1s: 


>>——ENVIRONMENT (COMMITTABLE) —*< 


The COMMITTABLE option and the INTERACTIVE file declaration attribute 
are mutually exclusive. 


A file with the COMMITTABLE option specified is placed in the commitment 
control environment when the file is opened. The file is then implicitly acted upon 
by the built-in subroutines PLICOMMIT and PLIROLLBACK. 


If the file cannot be placed under commitment control, a message is sent to the job 
log and the UNDEFINEDFILE condition (93) is raised. The UNDEFINEDFILE 
condition is also raised. if the file is not a data base file. 


If you want one or more different PL/I programs and two different run units, or a 
run unit and a non-PL/I program to open a file in the commitment control environ- 
ment, each run unit or non-PL/I program that will open the file must specify the 
COMMITTABLE option. 


Using the PLICOMMIT Built-In Subroutine 


The PLICOMMIT built-in subroutine processes commitment control functions. 


ee No a 
(character_expression) 


character_expression 
A character expression that can be converted to a non-varying character vari- 
able. A character string of zero length is equivalent to not specifying the argu- 
ment. 


PLICOMMIT processes the commitment control function by establishing a new 
commitment boundary for the job. 


e For files in a commitment control environment, all changes made to these files 
since the previous commitment boundary are made permanent. Changes are 
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made to all files under commitment control in the job, not just to those files in 
the program that calls PLICOMMIT. 


¢ For files in a commitment control environment, all record locks held by the job 
since the last commitment boundary are released and the records are made avail- 
able to other jobs. 


¢ PLICOMMIT only affects files under commitment control. If PLICOMMIT is 
called and there are no files under commitment control, no functions are proc- 
essed, and there is no error indication. 


¢ A file under commitment control may be closed or opened without affecting the 
status of any records that are pending a commit. The file does not have to be 
open in order to commit records for that file. For example, if since the last 
commitment boundary, records are updated in an open file and the file is then 
closed, a call to PLICOMMIT makes the updated records permanent and the 
file remains closed. 


¢ The end of a procedure or a run unit has no effect on the commitment control 
environment. Even though files are closed, all uncommitted changes remain 
pending. 


¢ The end of the job causes an automatic rollback of uncommitted records for all 
files under commitment control. Any uncommitted changes to the data base 
are cancelled. 


¢ The character_expression provides up to 2000 bytes of string data to be used as 
a description (commit id) for the commitment boundary. If the character- 
expression is not specified (or is length zero) no commitment boundary 
description is used. For further information, see the description of the 
NFYOBJ (Notify Object) parameter of the CL command STRCMTCTL in the 
Programming: Control Language Reference. 


PLICOMMIT does not do any of the following: 


e Change the position of a file. 
¢ Raise the ERROR condition. 
¢ Modify the I-O feedback area for a file. 
¢ Change the open or close state of a file. 


Using the PLIROLLBACK Built-In Subroutine 
PLIROLLBACK processes the rollback function by reestablishing a previous com- 
mitment boundary. 


>>—CALL—PLIROLLBACK—;—><« 


e PLIROLLBACK removes all changes that have been made to the files since the 
previous commitment boundary. This applies to all the files in a commitment 
control environment in the job, and not just those files in the program that 
called PLIROLLBACK. 


¢ For files in a commitment control environment, all record locks held by the job 
are released, and the records are made available to other jobs. 
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¢ The position of each file under commitment control is set to the previous com- 
mitment boundary. If the file was open at the previous commitment boundary 
and has since been closed, the position of the file is undefined. 


¢ PLIROLLBACK only affects files under commitment control. A call to 
PLIROLLBACK is ignored if there are no files under commitment control. 


e A file under commitment control may be closed and opened without affecting 
the status of any records that are pending a rollback. The file does not have to 
be open in order to rollback records for that file. If, since the last commitment 
boundary, records are updated and the file is then closed, this procedure 
removes the updated records and the file remains closed. 


¢ The end of a procedure or a run unit has no effect on the commitment control 
environment. Even though files are closed, any uncommitted changes remain 
pending. 


¢ The end of the job causes an automatic rollback of uncommitted records for all 
files under commitment control. Any uncommitted changes to the data base 
are cancelled. 


PLIROLLBACK does not do any of the following: 


e Raise the ERROR condition. 
¢ Modify the I-O feedback area for a file. 
e Change the open or closed state of any file. 


Using PLICOMMIT and PLIROLLBACK 


You must call the PLICOMMIT and PLIROLLBACK procedures at the appro- 
priate times in your PL/I program. 


Not all of the files that your program uses must be under commitment control. For 
example, a work file may not need the protection offered by commitment control. 


Performance Considerations 


Performance may be adversely affected by using commitment control. 
e Programs using commitment control may have longer run times. 


¢ Other jobs attempting to access files under commitment control may experience 
delays. 


You can avoid problems if you write programs so that a given file is always run 
under commitment control or else is never run under commitment control. It is 
more difficult to design a program so that it could run one time with commitment 
control] and another time without it. This is the case because the file and record 
lock recovery logic in a program depends upon if the file is under commitment 
control or not. 


Programs using commitment control can be run in multiple jobs concurrently. The 
system keeps track of the uncommitted data in each job. 
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Commitment control is not the only way to provide files with recovery capability. 
For information on other methods see Programming: Control Language Program- 
mer’'s Guide. 


Record Locks 


Record locks are specified on the LCKLVL parameter of the CL command 
STRCMTCTL: 


¢ *CHG specifies that only the records that you change in the files under commit- 
ment control are locked until they are committed or rolled back, or until the 
routing step ends. 


e «ALL specifies that any records that are accessed in any files in a commitment 
control environment are locked until they are committed or rolled back, or until 
the routing step ends. 


For further information on record locks, see the Programming: Control Language 
Prograrnmer's Guide. 


Use record locks to prevent changes to data in one job from interfering with data in 
another job. Because records changed under commitment control are not intended 
for use by other jobs until a PLICOMMIT or PLIROLLBACK 1s done, all records 
changed by a REWRITE, DELETE, or WRITE statement since the previous com- 
mitment boundary are locked. 


If, in one or more jobs, you use both committed and uncommitted data at the same 
time, you may find problems if either of the following conditions occurs: 


¢ Records in a physical file are accessed with commitment control and without 
commitment control at the same time. (For example, if there are two different 
logical files based on the same physical file.) This is a problem if the two files 
which access the records are in the same job or in different jobs. 


¢ You specify low level record locking (*«CHG) on the CL command 
STRCMTCTL for a file with INPUT attribute. 


When either of these conditions exist, records can be accessed in a data base file 
(even though no rollback or commit has been done yet) that have the following 
characteristics: 


¢ Records which have been updated by a REWRITE will contain the updated 
values. 


¢ Records which have been added by a WRITE will be present. 
¢ Records which have been deleted by a DELETE will not be present. 


Note: If an attempt is made to add a record through another access path with 
the same key as the deleted record, a KEY condition (duplicate key) will exist if 
duplicates are not allowed. 


You may avoid accessing uncommitted records from another job by placing the file 


under commitment control with a locking level of «ALL. Then, all READ state- 
ments on INPUT files attempt to obtain a lock on the record prior to reading the 
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record. Because uncommitted records are locked to the job that changed them until 
the PLICOMMIT or PLIROLLBACK is processed, the job requesting the record 
will wait until either the record is committed or rolled back, or the wait time ends 
(WAITRCD). 


The following tables show the relationship between the types of locks obtained, lock 
checking, and the record locking specified by the CL command STRCMTCTL. 


STATEMENT | OPEN OPTION LOCK LEVEL Record 


OR FILE 


ATTRIBUTES Maintained Operation PLICOMMIT 


C 


DELETE UPDATE 


UPDATE 


REWRITE UPDATE 

WRITE UPDATE 
or 
OUTPUT 


C 


Locked 
After 


or Statement 
| PLIROLLBACK 


Lock Next I/O Next 


BGNCMTCTL 


BGNCMTCTL 


BGNCMTCTL 


BGNCMTCTL |; 


Not Committed 


BGNCMTCTL 


! 


Notes: 


1. For DELETE or REWRITE, the lock state is checked before fora KEYED file 
only, not for a SEQUENTIAL file. 


2. If the next operation is a SEQUENTIAL DELETE or REWRITE, the lock 
state is maintained until the next PLICOMMIT or PLIROLLBACK. 
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Error Conditions 


The following run time conditions may arise due to problems in a commitment 


control environment: 
Condition Statement 
Involved 


ERROR DELETE 
ERROR REWRITE 
TRANSMIT READ 


UNDEFINEDFILE OPEN 


Figure 8-18. Run-time Conditions 


For more information on the meaning of these conditions, see the discussion of the 
appropriate condition in “Conditions” on page D-1. 


Recovery After a Failure 


For a system failure, the files under commitment control are automatically rolled 
back to the last commitment boundary when the system 1s restarted. 


For a job failure (either because of a user or system error), the files under commit- 
ment control are rolled back to the last commitment boundary as part of job end. 


Examples Using Commitment Control 
You may call a PL/I program in the commitment control environment with the fol- 
lowing CL statements: 


STRCMTCTL LCKLVL(*ALL) 
CALL PGM(LP1425) 
ENDCMTCTL 


The following example is a program updating a keyed file (see Figure 8-5 on 
page 8-10) that has been adapted for commitment control. 
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CC 5728PL1 RO1 MOO 880715 PL/I Source Listing 
LP1425: PROCEDURE; 


Be as londa teeta’ aati cers cee 


PLITST/LP1425 11/30/88 14:49:46 Page 2 


COM66160 
Include 


SEQNBR STMT.SUBS BLK BN DO hese ieee Deweetes ee 


100 1 A LP1425; PROCEDURE; COMB8160 830817 
200 COM00176 
300 /* FILE DECLARATIONS */ coNee1868 
400 2 11 DECLARE CoMo8198 
500 11 IN_FILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE — COM@0280 831013 
600 11 BUFSIZE(38)) .f 831013 
700021 11 MST_FILE FILE RECORD INTERNAL DIRECT UPDATE ENV(INDEXED COMMITTABLECOM@0210 830919 
800 11 KEYDISP(®) KEYLENGTH(10)),COM@0220 831114 
990 = 2.2 11 SYSPRINT FILE STREAM OUTPUT PRINT; 830607 
1900 ComMo0230 
1100 /* RECORD DECLARATIONS */ comeo24e 
1200 3 11 DECLARE COM00250 
1300 11 1 MASTER_RECORD, COMee266 831114 
14080 3.1 11 2 MASTER_KEY, comMe0280 
1500 (3.2 11 3 MASTER_GEN FLD CHAR(5), CoMeo290 
1608 = 33.3 11 3 MASTER_DET_FLD CHAR(5), ComMoo308 
1708 = 33.4 11 2 MASTER_NAME CHAR(20), COMe0310 
1800 (3.5 11 2 MASTER BAL PICTURE '999999V9R', CoMO6320 831013 
1999 «= 3.6 11 1 INPUT_RECORD, COM0G330 
2000 «= 3.7 11 2 INPUT_KEY, CoM0340 
2100 «© 3.8 11 3 INPUT_GEN FLD CHAR(5), COMB0350 
2200 ©3939 11 3 INPUT_DET FLD CHAR(5), COM00360 
2300 «S318 2S 2 INPUT_NAME CHAR(28), C0M06370 
2400S 3.11 1 1 2 INPUT_AMT PICTURE 'S99999V99'; COMO6380 831013 
2500 coee39e 
2600 /* PROGRAM FLAGS */ comee4oe 
27004 11 DECLARE CoMee416 
2800 11 1 BIT FLAGS STATIC, CoMee426 
2900 «41 11 2 MORE_RECORDS BIT(1) ALIGNED, coMee436 
3000 «= «4.2 11 2 NO BIT(1) ALIGNED INIT('8'B), comeo44e 
3100 4.3 11 2 YES BIT(1) ALIGNED INIT('1'B); COM00456 
: 3200 COMO0460 
3300 /* PROGRAM VARIABLES */ COMe0470 
34005 11 DECLARE couee4se 
3500 11 Fs PLICOMMIT BUILTIN, COMe0490 830615 
360005 1 11 PLIROLLBACK BUILTIN, COMO0506 830615 
3700S «5.2 11 OLD_MASTER_BAL PICTURE ‘S99999V99', COMe0518 
3808 «= «5.3 11 PAGE_NUMBER BINARY FIXED(2); comees2e 
3900 COM00530 
4080 —s«#G 11 ON ENDFILE(IN_FILE) CoMee546 
4100 11 MORE_RECORDS = NO; COMeesse 
4200 COMe8560 
43007 11 ON ENDPAGE (SYSPRINT) C0M80570 
4400 11 BEGIN; coMeesse 
4500 8 3 2 PUT FILE (SYSPRINT) PAGE EDIT('PAGE ',PAGE_NUMBER) COMO8590 
4600 3 2 (X(81) ,A(6),F(2))$ COMe0600 
47099 3 2 PUT FILE (SYSPRINT) SKIP(3) EDIT('UPDATE REPORT’) (X(38),A(13)); COM00610 
4ge0 = s:10 3 2 PUT FILE (SYSPRINT) SKIP(2) EDIT('KEY ID','NAME','CUR BALANCE', COM00620 
4900 3 2 "UPDATE AMOUNT', ‘NEW BALANCE") (A(6),X(9),A(4),X(21),A(11),  COM@0630 
5000 3 2 X(6) ,A(13) ,X(4) ,A(11))3 coMed64e 
5100011 3 2 PAGE_NUMBER = PAGE_NUMBER + 1; comeo6se 
5200 89:12 3 2 END; /* BEGIN */ COM80668 
5300 C0M60670 


Figure 8-19 (Part 1 of 3). PL/I Program Using Commitment Control 
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5728PL1 R@1 MOO 888715 


Include 
5400 
5500 
5600 
5700 
5800 
5908 
6600 
6168 
6200 
6300 
64060 
6500 
6600 
6700 
6800 
6900 
7600 
7100 
7200 
7300 
7400 
7500 
7600 
7700 
7800 
7900 
8900 
8100 
8200 
8300 
8400 
8500 
8600 
8700 
8800 
8900 
9000 
9100 
9200 
9300 
9400 
9500 
9600 
9700 
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10006 
10100 
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10460 
10506 
10690 
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1 
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SEQNBR STMT.SUBS BLK BN DO 


= ee 


ee 


PL/I Source Listing 
LP1425: PROCEDURE; 


R<, +, ee 


PLITST/LP1425 


/* MAIN PROGRAM */ 
PAGE_NUMBER = 1; 
MORE_RECORDS = YES; 


OPEN 

FILE (IN_FILE) TITLE('UPDATES'); 
OPEN 

FILE (MST FILE) TITLE('MSTFILE'); /* UPDATE */ 


/* INPUT */ 


SIGNAL ENDPAGE (SYSPRINT); 
READ FILE (IN_FILE) INTO (INPUT_RECORD); 


DO WHILE(MORE_RECORDS) ; 
IF INPUT DET FLD = ' ' THEN 
CALL INITSEQ; 
ELSE 
CALL DYNAMIC; 
READ FILE (IN_FILE) INTO (INPUT_RECORD) ; 
END; /* DO WHILE */ 


CLOSE 

FILE (IN_FILE); 
CLOSE 

FILE (MST_FILE); 


INITSEQ: PROCEDURE; 
MASTER_GEN FLD = INPUT_GEN FLD; 
READ FILE (MST_FILE) INTO (MASTER_RECORD) KEY (MASTER_KEY) 
OPTIONS(KEYSEARCH(EQLAFT) NBRKEYFLDS(1)); 
DO WHILE(INPUT GEN FLD = MASTER_GEN FLD); 
CALL SEQPROC; 
END; /* DO WHILE */ 
RETURN; 
END INITSEQ; 


SEQPROC: PROCEDURE; 
PUT FILE (SYSPRINT) SKIP EDIT(MASTER_KEY,MASTER_NAME, 
MASTER_BAL) (A(5) ,A(5) .X(5) ,A(20) ,X(6),F(10,2)); 
READ FILE (MST_FILE) INTO (MASTER_RECORD) KEY(MASTER_KEY) 
OPTIONS (KEYSEARCH(AFTER) ) ; 
RETURN; 
END SEQPROC; 


DYNAMIC: PROCEDURE; 
MASTER_KEY = INPUT_KEY; 
READ FILE (MST_FILE) INTO (MASTER RECORD) KEY(MASTER_KEY) 
OPTIONS (KEYSEARCH(EQUAL)); 
IF INPUT_GEN_FLD = MASTER_GEN FLD THEN 
DO; 
OLD _MASTER_BAL = MASTER_BAL; 
MASTER_BAL = MASTER_BAL + INPUT_AMT; 
PUT FILE (SYSPRINT) SKIP EDIT(MASTER_KEY,MASTER_NAME, 


11/36/88 14:49:46 


Page 3 
COMO0160 


es ee. cee ae, Pe ee, Se ae, OR. Pen, PePae > Peer. MeN ce ere, ere | Date 


COM00680 
COM90690 
COM0a700 
CQM00710 
COM00720 
COM00730 831613 
COM08740 
COMGO758 830919 
COM00760 
COM00770 
COM00780 
COM90790 
COM00808 
COM00810 
COH00820 
COM00830 
COM00846 
COM00850 
COM00868 
COM00870 
COMO0880 
COH00890 
COM00900 
COMO8910 
COM00920 
C0M00930 
COM00940 
COM00950 831013 
COM60960 831013 
COMG0976 
COMO0986 
COMO0996 
COM01600 
COM01610 
COHM01020 
COMO01030 
COM01076 831013 
COM01088 831013 
COM01040 831013 
COM01058 831013 
COMO01090 
COMO01100 
COM01110 
C0M01120 
COM01136 
COM@1146 831613 
831013 
COM61150 
COMG1166 
C0OMO1170 
COM01180 
C0OMO1190 


OLD_MASTER_BAL, INPUT_AMT,MASTER_BAL) (A(5),A(5),X(5),A(20), COMO1200 831613 


Figure 8-19 (Part 2 of 3). PL/I Program Using Commitment Control 
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Cc 5728PL1 R@1 MOO 880715 PL/I Source Listing PLITST/LP1425 11/30/88 14:49:46 Page 4 
LP1425: PROCEDURE; COM00160 
Include SEQNBR STMT.SUBS BLK BN DO PW ice ete be Sas Ohne Ft Ae Ss aks EA a Pio oS ea ivka Oak a Pde det cas 8 Date 
10700 6 21 X(6) ,F(10,2) ,X(6),F(10,2),X(8),F(10,2)); COMO1216 831013 
10800 496 46 621 REWRITE FILE (MST_FILE) FROM (MASTER_RECORD) KEY(MASTER_KEY); COM01220 
16960 COM61230 
11006 47 6 2 1 4 IF MASTER_BAL >= 6.@ THEN come1246 
11100 6 21 DO; COMe1250 
11200 48 6 2 2 5 CALL PLICOMMIT; COM01260 836615 
11306 49 6 2 2 PUT FILE (SYSPRINT) EDIT('* TRANSACTION COMMITTED *') COM01270 831013 
11406 6 2 2 (X(1),A(26))¢ COM61280 831613 
11500 50 6 2 2 END; /* DO */ COMe1290 
11606 8651 6 2 1 ELSE COM81300 
11760 6 2 1 DO; COM@1310 
11800 ©6552 6 2 2 CALL PLIROLLBACK; COM01320 830615 
11990 53 6 2 2 PUT FILE (SYSPRINT) EDIT('* TRANSACTION ROLLEDBACK *') COM01330 831013 
12000 6 2 2 (X(1),A(26)): COM01340 831013 
12100 54 6 2 2 END; /* DO */ COM@1350 
12200 COM01360 
12300 §3= 55 6 2 1 END; /* DO */ C0M61370 
12400 ©8656 6 2 RETURN; COMe1380 
12500 57 6 2 END DYNAMIC; COMQ1390 
12660 COMe1400 
12700 §3=s- 58 1 1 END LP1425; COM01410 830817 


Figure 8-19 (Part 3 of 3). PL/I Program Using Commitment Control 


See Figure 8-5 on page 8-10 for an explanation of this same program 
without commitment control. 

Code the COMMITTABLE option in the ENVIRONMENT attribute. 
Declare the built-in subroutines PLICOMMIT and PLIROLLBACK. 


Check for successful transactions. 


Commit the transaction, 


Hoe 


Or roll back the transaction. 


The following example uses a display file and indicators to check for a successful 
transaction in a program to update a file. 


Chapter 8. Using AS/400 Files 8-67 


COMMITMENT CONTROL 


IRM International Business Machines AS/400 DATA DESCRIPTION SPECIFICATIONS dei ef i 


Printed WU.S.A, 
eNurnber af sheata per pod may vary slightly. 


pe tenying cement TTT ETT Oaseription romp 
Lrregrammer tte ei 


% Data Type ty A/P/S/B/F ALS//1/N/1//D/M) 
Uaage (6/0;1/6/H/a//P) 


$ pacima 
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F SCREEN [FOR COMMI TMENT CONTROL 
| fee ie AMOUNT 


[{ oO  TENDATA 


rT _T__|TEXT( CUSTOMER ACCOUNT PROMPT 
FoF ooo AO1(15 ‘END OF PROGRAM ') 


aaa a 
PATTY | IPUTRETAIN OVERLAY 
A tt tt 8 "ACCOUNT MASTER UPDATE‘ 


rT All iftt | [T_3.__ 3) FROM ACCOUNT NUMBER’ 
Ro CCTFR CGT FROM} | SO 3 23CHECK (ME) 

| Cl BB TT tt tT ERRMSG C'INVALID FROM ACCOUNT + 
POULT TT Tt NUMBER 99) 


——A{ Pay ft Tp | _ERRMSBCCINSUFFICIENT FUNDS IN FROM 4 

LAL | ACCOUNT* 98 

PLT a "TO ACCOUNT NUMBER® 

jp ALT TT TT it aAcetro [ |i SY OI 4) 23CHECK(ME) 

TAT a ERRMSG ( INVALID TO ACCOUNT + 
PAL TT TT PT NUMBER' 97) 

Se 0c 6 em OL - "AMOUNT TRANSFERRED * 

Ames 9 (Ee a a (ae a a (eee 


Figure 8-20 (Part 1 of 6). Program Using PLICOMMIT and PLIROLLBACK 


TRY AS/400 DATA DESCRIPTION SPECIFICATIONS Gx2{-9891-0 UM/060s 


Print «S.A. 
International Business Mochines eNuraber of nheets per pod jt po dale i 


a 
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Include 


ACCTPMT 
ACCTPMT 
ACCTPMT 
ACCTPMT 
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LP1426: PROCEDURE; CcT66166 
Re HeccodesvetecccrecceMacccdecestececdecactecesDancntecesMecncPoccedermeeteseed Date 
LP1426: PROCEDURE; CCT66166 836817 
CCT66176 
/* FILE DECLARATIONS */ CCT66188 
DECLARE CCT66190 


ACT_FILE FILE RECORD INTERNAL DIRECT UPDATE ENV(INDEXED COMMITTABLECCT60260 830919 
KEYDISP(6) KEYLENGTH{5)),CCT@6216 830919 


ACCTFMTS FILE RECORD INTERNAL SEQUENTIAL UPDATE ENV(INTERACTIVE); 


/* RECORD DECLARATIONS */ 


DECLARE 
1 FROM_ACCOUNT_RECORD, 
2 ACCT_KEY PICTURE '9999R', 
2 NAME CHAR(26), 
2 ADDR CHAR(26), 
2 CITY CHAR(26), 
2 STATE CHAR(2), 
2 ZIP PICTURE '99999R', 
2 BALANCE PICTURE '99999999V9R’, 
1 TO_ACCOUNT_RECORD, 
2 ACCT_KEY PICTURE '9999R', 
2 NAME CHAR(26) 
2 ADDR CHAR(26), 
2 CITY CHAR(26), 
2 STATE CHAR(2), 
2 ZIP PICTURE '99999R', 
2 BALANCE PICTURE '99999999V9R'; 
DECLARE 


1 DISPLAY_RECORD, 
S INCLUDE ACCTFMTS(ACCTPMT, INPUT, , COMMA) ; 


DEVICE FILE: ACCTFMTS.LP1426 

FILE CREATION DATE: 87/11/36 

RECORD FORMAT: ACCTPMT 

RECORD FORMAT SEQUENCE ID: 11FB70353213F 


INDICATORS FOR FORMAT ACCTPMT 


INDICATOR 15 END OF PROGRAM 

INDICATOR 94 INVALID TRANSACTION AMOUNT INPUTTED 
INDICATOR 97 INVALID TO ACCOUNT NUMBER 

INDICATOR 98 INSUFFICIENT FUNDS IN FROM ACCOUNT 
INDICATOR 99 INVALID FROM ACCOUNT NUMBER 


15 ACCTFROM PIC ‘9999R', 
15 ACCTTO PIC '9999R’, 
15 TRANSAMT PIC '99999999V9R', 
1 DISPLAY_INDICATORS, 
“INCLUDE ACCTFMTS(ACCTPMT, INDICATORS, , COMMA) ; 


DEVICE FILE: ACCTFMTS.LP1426 

FILE CREATION DATE: 87/11/30 

RECORD FORMAT: ACCTPMT 

RECORD FORMAT SEQUENCE ID: 11FB7D353213F 
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*/ 
*/ 
my 
*/ 
*/ 


CCT66226 836607 
CCT66230 
CCTee240 
CCT66258 
CCT66266 
CCT66276 831013 
CCT66280 
CCT60290 
CCT66368 
CCT60310 
CCT60328 831013 
CCT06330 831013 
CCTeG340 
CCT66356 831013 
CCT60360 
CCT@6370 
CCT66386 
CCT60390 
CCT66408 831613 
CCT60416 831613 
831613 
831613 
CCT06420 
CCT66430 831013 


CCTe6446 
CCT8@450 836919 


8-69 


COMMITMENT CONTROL 


5728PL1 RO1 MOO 880715 


Include 
ACCTPMT 
ACCTPNT 
ACCTPMT 
ACCTPMT 
ACCTPMT 
ACCTPMT 
ACCTPNT 
ACCTPMT 
ACCTPMT 
ACCTPMT 
ACCTPMT 


ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 


ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 
ERRFMT 


Figure 


SEQNBR STMT.SUBS BLK BN DO 
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/* INDICATOR FLAGS */ 
DECLARE 
1 INDICATOR_FLAGS STATIC, 
2 OFF 
2 ON 


/* BUILT-IN FUNCTIONS */ 
DECLARE 

ONCODE 

PLICOMMIT 

PLIROLLBACK 


/* PROGRAM VARIABLES */ 
DECLARE 
OPERATION 


PICTURE '9' INIT(6), 
PICTURE '9" INIT(1); 


BUILTIN, 
BUILTIN, 
BUILTIN; 


CHAR(9); 
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CCT00500 
CCT00518 
CCT00520 
CCT00530 
CCT00540 
CCT80550 
CCT00560 
CcT00570 
CCT@0580 
CCT00590 
CCTO0600 
CCT00610 
CCTO0620 
CCT00630 
CCT08640 
CCTO8650 
CCT00660 
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LP1426: PROCEDURE; CCT00160 
ME 4 yee d Laie GF ilid cine vase Pee os Oca he oes Neen etuces Sic tae tine Coed a heise lie estes & Date 
[* ------- CUSTOMER ACCOUNT PROMPT----------------------------------- */ 
15 INO1_IN14 CHAR(14), /* UNDEFINED INDICATOR(S) */ 
15 IN15 PIC '9', /* END OF PROGRAM */ 
15 IN16_IN93  CHAR(78), /* UNDEFINED INDICATOR(S) */ 
15 IN94 PIC '9', /* INVALID TRANSACTION AMOUNT 
INPUTTED x/ 
15 IN95_IN96 CHAR(02), /* UNDEFINED INDICATOR(S) */ 
15 IN97 PIC '9', /* INVALID TO ACCOUNT NUMBER */ 
15 IN98 PIC '9', /* INSUFFICIENT FUNDS IN FROM 
ACCOUNT */ 
15 IN99 PIC '9', /* INVALID FROM ACCOUNT NUMBER */ 
1 ERROR_FORMAT,  €CT86460 
%INCLUDE ACCTFMTS{ERRFMT , OUTPUT, , COMMA) ; CCT00476 831013 
/* Be coe eS aS ce Sees t Sess Soe See ee ae 2 te nee See ees eee x/ 
/* DEVICE FILE: ACCTFMTS.LP1426 */ 
/* FILE CREATION DATE: 87/11/30 */ 
/* RECORD FORMAT: ERRFMT */ 
/* RECORD FORMAT SEQUENCE ID: 0061A19C6D524 */ 
/* aE Ta ya Ne A a I 0 EI Tt ae Nt Spt eg A x/ 
/* INDICATORS FOR FORMAT ERRFMT */ 
/* INDICATOR 95 aa 
/* INDICATOR 96 */ 
/* Na ce ee Se eee eo RS ae TRESS Pon IS AYE RES RYE EL See Ee RC RES PP */ 
15 DUMMYDCL  CHAR(@), /* NO FIELDS OF NEEDED TYPE */ 
1 ERROR_FORMAT_INDICATORS, CCT00480 
%INCLUDE ACCTFNTS(ERRFMT, INDICATORS) ; CCT80490 830607 
/* sss ca sel ee eS as ge Sa i esa a a eae lg ees etal oe x/ 
/* DEVICE FILE: ACCTFMTS.LP1426 */ 
/* FILE CREATION DATE: 87/11/30 */ 
/* RECORD FORMAT: ERRFMT */ 
/* RECORD FORMAT SEQUENCE ID: 0061A19C6D524 * / 
/* oa voeboewees bo. 366 eee cee 2 oe oe ec Sede écse ec edSece ce seco eee x/ 
15 IN@1_IN94 CHAR(94), /* UNDEFINED INDICATOR(S) x / 
15 IN95 PIC '9', 
15 IN96 PIC '9', 
15 IN97_IN99 CHAR(03); /* UNDEFINED INDICATOR(S) */ 


831613 
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836919 
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Include 
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6000 
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8000 
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LP1426: PROCEDURE; CCT80160 
PSG ® Kees bags Vas Vale Cat ON-y Ode ooo Wie et oe ON WS Oe aele se OC RE Ve Red ver ea ao 
ON KEY (ACT_FILE) CCT00676 
BEGIN; CCT08680 
ON ERROR SYSTEM; CCTO00690 
IF ONCODE -= 51 THEN CCT00700 
IN96 = ON; CCT00710 
ELSE CCT00720 
IF OPERATION = 'REWRITE' THEN CCT00730 
IN95 = ON; CCT00740 
ELSE CCT00750 
IF OPERATION = 'READ-FROM' THEN CCT00760 
DO; CCT00770 
IN99 = ON; CCT00780 
GO TO LAB1; CCT00790 
END; /* DO */ CCT00800 
ELSE CCT00810 
IF OPERATION = 'READ-TO' THEN CCTO0820 
DO; CCT00830 
IN97 = ON; CCT00840 
GO TO LAB2; CCTO0850 
END; /* DO */ CCTO0860 
WRITE FILE (ACCTFMTS) FROM (ERROR_FORMAT) CCT00870 
OPTIONS(RECORD('ERRFMT') INDICATORS(ERROR_FORMAT_INDICATORS) ) ; CCTO0886 
CLOSE CCT00890 
FILE (ACT_FILE); CCTO00908 
CLOSE CCT00916 
FILE (ACCTFMTS); CCT00920 
STOP; CCT00930 
END; /* BEGIN */ CCT00940 
CCT00950 
/* MAIN PROGRAM */ CCT00960 
OPEN CCT00970 
FILE (ACT_FILE) TITLE('ACTFILE'); /* UPDATE */ CCTO0980 
OPEN CCTO0990 
FILE (ACCTFMTS); /* UPDATE */ CCT01900 
CCT01010 
DISPLAY_INDICATORS = OFF; /* IN15,1N94,1N97,1N98,IN99 */ CcT61020 
ERROR_FORMAT_ INDICATORS = OFF; /* IN95,IN96 */ CCTO1030 
CCTG1046 
/* DISPLAY THE SCREEN */ CCT01050 
CALL DISPLAY; CCT01060 
CCT01070 
DO WHILE(IN15 = OFF); CCT01080 
/* CHECK FOR INVALID TRANSACTION AMOUNT */ 
IF TRANSAMT < 8.06 THEN 
DO; 
IN94 = ON; 
GOTO LAB3; 
END; 
/* VERIFY FROM-ACCOUNT */ CCT01090 
FROM_ACCOUNT_RECORD.ACCT_KEY = ACCTFROM; CCTO01100 
OPERATION = 'READ-FROM'; CCT01110 
READ FILE (ACT_FILE) INTO (FROM_ACCOUNT_RECORD) CCT01120 
KEY (FROM_ACCOUNT_RECORD.ACCT_KEY); CCT01130 


Figure 8-20 (Part 5 of 6). Program Using PLICOMMIT and PLIROLLBACK 


Chapter 8. Using AS/400 Files 


4 


Date 


830607 


838607 


830919 
830919 
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831102 
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LP1426;: PROCEDURE; CCT66166 
Include SEQNBR STMT.SUBS BLK BN DO Ret occa Lace a Pecan le vue Paw eeces ea tscs 6A suse Peves Oeaects gc QesssPireet (Peet oosce: DALE 

10766 CCT01146 

18866 38 111 LAB1: IF IN99 = OFF THEN CCT61158 

16960 111 DO; CCT@1160 

11066 /* VERIFY TO-ACCOUNT */ CCT01170 

11166 39 1 1 2 TO_ACCOUNT_RECORD.ACCT_KEY = ACCTTO; CCT61186 

11268 40 1 1 2 OPERATION # 'READ-TO'; CCT01190 

11306 41 11 2 READ FILE (ACT_FILE) INTO (TO_ACCOUNT_RECORD) CCT61200 

11408 112 KEY (TO_ACCOUNT_RECORD.ACCT_KEY); CCT01210 

11506 CCT01226 

11660 42 112 LAB2: IF IN97 = ON THEN CCT61238 

11708 1 12 4 CALL PLIROLLBACK; CCT@1246 830919 

11866 43 11 2 ELSE CCT01258 

11960 11 2 DO; CCT61260 

12606 /* UPDATE THE ACCOUNT */ CCT01276 

12106 44 1 1 3 FROM_ACCOUNT_RECORD.BALANCE = CCT01280 

12206 1 1 3 FROM_ACCOUNT_RECORD.BALANCE - TRANSAMT; CCT61298 

12306 45 1 1 3 TO_ACCOUNT_RECORD.BALANCE = CCT01306 

12468 1 1 3 TO_ACCOUNT_RECORD.BALANCE + TRANSAMT; CCT01310 

12500 46 1 1 3 OPERATION = ‘REWRITE’; CCT01326 

12600 47 1 1 3 REWRITE FILE (ACT_FILE) FROM (FROM_ACCOUNT_RECORD) CCT@1336 

12700 1 1 3 KEY (FROM_ACCOUNT_RECORD.ACCT_KEY) ; CCT01340 

12860 48 1 3 REWRITE FILE (ACT_FILE) FROM (TO_ACCOUNT_RECORD) CCT@1350 

12900 11 3 KEY (TO_ACCOUNT_RECORD.ACCT_KEY); CCT01366 

13000 49 1 1 3 3] IF FROM_ACCOUNT_RECORD.BALANCE < 0.0 THEN CCT01376 

13160 11 3 DO; 831162 

13260 50 11 4 4} CALL PLIROLLBACK; CCT01386 836919 

13300 51 11 4 IN98 = ON; 831102 

13400 52 114 END; 831102 

13500 53 11 3 ELSE CCT01390 

13600 11 3 5] CALL PLICOMMIT; CCT91466 836919 

13700 54 11 3 END; /* DO */ CCT01416 

13806 55 1 1 2 END; /* DO */ CCT01420 

139060 56 111 LAB3: 831102 

14000 111 CALL DISPLAY; CCTO91436 831162 

14100 57 111 END; /* DO WHILE */ CCT61446 

14200 CCT61456 

14300 58 1 1 CLOSE CCT01460 

14400 1 1 FILE (ACT_FILE); CCT01476 

14500 59 1 1 CLOSE CCT@1480 

14660 1 ae FILE (ACCTFMTS); CCTQ1490 830607 

14760 CCT@1560 

14800 60 1 1 DISPLAY: PROCEDURE; CCT@1510 

14900 /*® DISPLAY THE SCREEN AND READ */ CCT01520 

15000 61 3 2 WRITE FILE (ACCTFMTS) FROM (DISPLAY_RECORD) CCT91530 830607 

15100 3 2 OPTIONS(RECORD('ACCTPMT') INDICATORS(DISPLAY_INDICATORS)); CCT@1548 

15200 62 3 2 DISPLAY_INDICATORS = OFF; /* IN15,1N94,1N97,IN98,IN99 */ CCT01556 831182 

15300 63 3 2 READ FILE (ACCTFMTS) INTO (DISPLAY_RECORD) CCT01566 830607 

15400 3: 2 OPTIONS(RECORD('ACCTPHT') INDICATORS (DISPLAY_INDICATORS) ); CCT01570 

15500 64 3 2 END DISPLAY; CCT01580 

15606 CCT61596 

15700 65 1 1 END LP1426; CCT01660 830817 
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ACCOUNT MASTER UPDATE 


FROM ACCOUNT NUMBER 11111 
TO ACCOUNT NUMBER 12345 
AMOUNT TRANSFERRED 5. 


MAKE SURE THAT YOU INSERT A DECIMAL POINT 
EVEN IF THERE ARE NO CENTS INVOLVED. 


DO NOT PLACE ANY TYPE OF SYMBOL IN FRONT OF OR BEHIND 
THE NUMBER (E.G. $, PLUS SIGN, MINUS SIGN, ETC.). 


Figure 8-21. Display for Program Using PLICOMMIT and PLIROLLBACK 


Code the COMMITTABLE option in the ENVIRONMENT attribute. 
Declare the built-in subroutines PLICOMMIT and PLIROLLBACK. 
Check for successful transactions and: 


Either roll back the transaction, 


on & 


Or commit the transaction. 


Using the %INCLUDE Directive for External File Descriptions 


The %INCLUDE directive can be used to copy external text into the source 


program, and to copy data description specifications (DDs) for externally described 
files into the source program. 


The %INCLUDE directive has a different format for each of the following 
functions: 


e Copying source text into a source program. 


The syntax diagram and description of this function can be found in “Using the 
“INCLUDE Directive” on page 2-16. 


e Copying record formats from AS/400 files into PL/I programs. 
This function of the % INCLUDE directive is discussed below. 


The syntax of the %“ INCLUDE directive used for copying record formats from 
AS/400 files into PL/I programs is shown below: 
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>>—% INCLUDE——file_name—(format_name—,element_type——> 


prefix_name—, comma 


file_name 


An identifier of up to 10 characters. The file is located by using the *LIBL 
search list in effect at compile time. The file name can begin with and contain 
numeric characters and periods and can use all the characters allowed in a 


System/38 name. 


format_name 


You cannot name your file SYSLIB. 


Name of the record format included. The name must follow the rules for 
naming AS/400 objects. 


element_type 


Specifies the fields and indicators that are included. The possible types are: 


INPUT 


OUTPUT 


KEY 
INDICATORS 


RECORD 
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Generates the record definition that matches the input buffer 
for data base or device files. Includes fields that have a usage 
of INPUT or BOTH in pps. For subfiles, output fields are 
also included. The response indicators are also included 
when the DDs keyword INDARA is not specified in the 
external file description. 


Generates the record definition that matches the output 
buffer for data base files only. Includes fields that have a 
usage of OUTPUT or BOTH in DDs. The option indicators 
are also included when the DDs keyword INDARA is not 
specified in the external file description. 


Includes fields that are specified as keys in DDS. 
Defines a 99-byte area for indicators. 


When you specify INDICATORS, you must also specify the 
following: 


¢« The pps keyword INDARA in the external description 
of the file. 


¢ The INDICATORS parameter on the OPTIONS option 
of any record I/O statements for the file. 


Generates the record definition that matches both the input 
and the output buffers that are used by physical and logical 
files. Includes fields that have a usage of BOTH in DDs. 
INPUT fields in logical files are also included. It includes 
any indicators that are used as option indicators and also as 
response indicators if INDARA is not specified in the 
external file description. 


USING THE %INCLUDE DIRECTIVE 


prefix_name 
A character string by which all generated names are prefixed. The prefix is 
limited to 30 characters or less. The resulting names must be valid and the 
length must be 31 characters or less. 


COMMA 
Specifies that the last data element of the record or key structure is followed by 
acomma. If COMMA is not specified, the last data element is followed by a 
semicolon. The COMMA option may be used to position the data elements 
generated by the % INCLUDE directive within a structure without ending the 
structure. 


Using the “INCLUDE Directive with Externally Described Files 
When you explicitly declare a file in your program with the DESCRIBED option of 
the ENVIRONMENT attribute, the following checks are processed for each record 
format copied into the program from the file with a % INCLUDE directive: 


e Level checking, at open time, for each record format. For more information on 
level checking, see the Programming: Control Language Programmer's Guide. 
To prevent level checking, you may specify no level checking when you create 
the file, or you may override the default level checking after the file is created 
(see the CL command CRTxxxF (Create xxx File) and OVRxxxF (Override xxx 
File) in the Programming: Control Language Reference). 


¢ The compatibility of the program description of the file (ENVIRONMENT 
options) and the external description of the file (DDs) (see Figure 7-2 on 
page 7-9). 
If the externally defined file 


¢ Has no fields defined for it, or 


e The element type is INPUT and there exists no fields in the record format with 
usuage INPUT or BOTH, or 


¢ The element type is OUTPUT, the file is not a data base file and there exists no 
fields in the record format with usage OUTPUT or BOTH, or 


e The element type is INDICATORS but no separate indicators exist 


then the compiler will generate the following declaration: 
15 DUMMYDCL CHAR(0); 
and will produce a comment in the listing and issue a severity 10 warning message. 


See Figure 8-23 on page 8-79. 


For example, a DOUMMYDCL statement is generated by a subfile control record 
format (which has no record fields and exists to define indicators and communicate 
with the system). 


Even if no fields are included and a DUMMYDCL is generated, the compiler proc- 
esses level checking and compatibility checking. 


If you specify DESCRIBED but do not use the “INCLUDE directive in your 
program, no level checking is processed. This is not the normal case but is accept- 
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able because the DESCRIBED attribute may be used to obtain functions other than ) 
level checking. 


Using the “%INCLUDE Directive with Program-Described Files 
If DESCRIBED is not specified, the % INCLUDE can be used to generate record 
format definitions, but no level checking occurs when the file is opened. 


Using the “%INCLUDE Directive with Display Files 
Input and Output 


The INPUT and OUTPUT options are provided for display files. The INPUT 

option generates fields that have a Dps field usage of INPUT or BOTH, giving a 

record definition that matches the input buffer. The OUTPUT option generates 

fields that have a DDS field usage of OUTPUT or BOTH, giving a record definition 

that matches the output buffer. J 


If you are using a single record format for both input and output, you should use 
the % INCLUDE directive twice, specifying element-type INPUT one time and 
element-type OUTPUT the other time. To avoid duplicating the definition of the 
record format, you may do one of the following: 


e Use a unique prefix 
¢ Include each use of INPUT and OUTPUT in a unique structure. 


For example: -) 


DECLARE 
1 DISPLAY SCREEN, 
5 INPUT FIELDS, 
INCLUDE FLOREFFILE(INFIELDS, INPUT, ,COMMA) ; 
5 OUTPUT FIELDS, 
INCLUDE FLOREFFILE(OUTFIELDS , OUTPUT) ; 


If you specify the PL/I type INPUT, either INPUT or BOTH fields should exist in 
the DDs description of the record format. If you specify the PL/I type OUTPUT, J 
either OUTPUT or BOTH fields should exist in the DDs description of the record 

format. In either case, if no such fields exists in the record format, the compiler will 
generate a DUMMYDCL. 


Indicators 


You can define the indicators for a record format as part of a separate area, inde- 
pendent of the record format, or you can define them as fields in the record format. 
For a discussion of these methods for using indicators, see the sections below, and 
refer to ‘INDICATORS Parameter” on page 7-19. 


Indicators in a Separate Area: If you are using indicators in a separate area, make 
sure that you have done all of the following: 


¢ Specify INDICATORS type on the % INCLUDE directive. ; 
¢ Specify the DDs keyword INDARA on the external description of the file. 
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¢ Specify INDICATORS on the OPTIONS option of any input/output statement 
that accesses the record format. 


Indicators defined for a record format, both at the file level and at the record level, 
are returned as comments in the header description for each % INCLUDE directive 
when INPUT, OUTPUT, RECORD, or KEY is specified, if indicators are in a 
separate indicator area. 


Indicators as fields In the record format: Indicators in the buffer are declared as 
fields in the record when INPUT, OUTPUT, or RECORD is specified. 


When the indicators are defined in the record buffer, names are generated in the 
form of INnn where nn is the number of the indicator for each indicator that is 
used. 


DDS to PL/I Mapping 
The following table shows how each DDs data type is defined in a PL/I program: 


DDS | Length Decimal | Generated 
Data Position | PL/I 
Type Declaration 


indi- | 1 PICTURE '9! Yes 
cator 
1 - 32 766 CHARACTER (n) 
res n = 1 to 32 ee ee 


0 _—| BINARY FIXED | BINARY FIXED (15) UNALIGNED | UNALIGNED Yes | 


a en 
fp [i-4[i-4 [CHARACTER @ «(No 
ip [s-9 [1-9 [enaracten [x2 


1-15 - 15 DECIMAL FIXED (p,q) 
where: 
p = lto 15 
qg = Oto 15 
16- 31 CHARACTER (n) 
where n = ~ 2+ 1 
16- 31 0-31 CHARACTER (n) 
where n = 16 to 31 


Figure 8-22 (Part 1 of 2). How DDS Data Types Are Defined in a PL/I Program 
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DDS | Length Decimal | Generated 
Data Position | PL/I 
Pe Declaration 


- 15 DECIMAL FLOAT (16) UNALIGNED Yes 
where n = | to 15 


Figure 8-22 (Part 2 of 2). How DDS Data Types Are Defined in a PL/I Program 


DDS Features You Can Use in Your PL/I Program 
ALIAS keyword 


If you use the keyword ALIAS in your Dps, the name you specify as the ALIAS 
parameter is the name that the compiler generates in your program. The field name 
specified in the DDs is ignored. By using the ALIAS-name, you can make full use 
of PL/I’s 31-character name length limit, with resulting improvements in program 
readability. You are not limited to a 10-character field-name. For an example of 
the use of the ALIAS keyword, see Figure 8-23 on page 8-79. 


Indicators 


The element type INDICATORS in the %INCLUDE directive generates a 99 byte 
structure for indicators. Each indicator defined in DDs generates a field declaration 
in the form INnn, where nn is the DDs indicator number. All other bytes in the 
structure, for which indicators have not been defined, generate field declarations in 
the form INnn_INmm, where nn is the first undefined byte, mm is the last unde- 
fined byte, and the bytes are contiguous. For example, if one indicator, 51, was 
defined, then the indicator structure would be: 


INO1_INSO 
INS] 
IN52_IN99 


Defined indicators will generate a PICTURE '9' and undefined indicators will gen- 
erate CHAR(n), where n represents the number of consecutive indicators not 
defined. 


For indicators in the buffer, only the indicators that are used are declared. They are 
declared as PICTURE '9' and are generated when the element-type INPUT, 
OUTPUT, or RECORD is specified. 


Key definitions 


The element-type KEY in the %INCLUDE directive declares all the fields that are 
specified in the DDs as keys; their attributes are given in comments. For example, 
/x ASCENDING +#/ is generated if the key field is ascending. Similarly, when you 
specify INPUT, OUTPUT, or RECORD in the % INCLUDE directive, a field- 
level comment indicates that the generated element is a key field in the DDs. 
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Prefixes 
If you code a prefix-name in your % INCLUDE directive, the prefix you specify will 
be attached to the field name supplied by the file. For example, if you code 
%INCLUDE STOCKFILE(COUNT,RECORD,CURRENT_} 
and in the DDs the first field in the record is named 
BANDSAWS 
the generated name is 
15 CURRENT BANDSAWS 


By using prefixes, you can generate meaningful names for different uses of the same 
record format inside a single program. For an example of the use of a prefix, see 
Figure 8-23. 


TEXT keyword 


The DDs keyword TEXT at the field level generates a comment line for the field 
declarations. Similarly, the keyword TEXT at the format level generates a comment 
line preceding the declarations taken from the DDs. 


Sample Program Showing Use of DDS Features 


== Ai International Business Machines 


AS/400 DATA DESCRIPTION SPECIFICATIONS GXx21-9891-0 UM/050« 


Printed In U.S.A. 
Number of sheets per pod may vary alightly. 


Condiilan Nome 


~ And/Or/Camment (A/G/«) 


123643 


Tyce of Name of Spec (B/R/H/I/K 73/0) 


| AAT 


ee eg 


Al 


‘Bo2t Le 1? 24-23 28 27 wis wo Ml Pr AS 34 


CUSTF pase Hoewens 
a 


ao eee es ae a 
a 


B/F ASS/K/Y/N/LS OOS) 


Data Type hb A/P/3S/ 


Dime See G 
TL [ ICUSTADDR2 [| 25a | 
AA | il | fe eee en TEXTC'CUSTOMER BUSINESS ADDRESS' > 
4 Oo [ [| ws [| [| |TEXTC'CUSTOMER NUMBER') 
AA, {/ [| ki custnao [| [|  {{] [| [UNSIGNED 
(aaa (EE he 


Figure 8-23 (Part 1 of 3). % INCLUDE Examples 
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5728PL1 RO1 MOO 886715 


Include 


CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 


CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 
CUSTFMT 


SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 
SFLREC 


SFLCTL 
SFLCTL 
SFLCTL 


++ + + +e ee eee + + + 


+ + + + + + + + + + 


++2+4+4+74+ 744 ¢ + + + 


+ + + 


106 
200 
308 
408 
500 
108 
200 
309 
460 
500 
600 
700 
800 
900 
1000 
1100 
1206 
1306 
1400 
600 
700 
800 
100 
200 
306 
408 
500 
600 
700 
800 
908 
1000 
900 
1080 
1100 
108 
200 
300 
400 
500 
606 
706 
800 
900 
1000 
1106 
1200 
1300 
1200 
1300 
108 
200 
306 


1 


2 


N PO 
eo 


2.4 


3.1 


SEQNBR STMT.SUBS BLK BN DO 


PL/I Source Listing QTEMP/LP1430 11/30/88 15:31:28 Page 2 
LP1430: 
RE ate cccdiccteccakeccsteccsdesceteceshessetssredcccetscecBeacctocessePesteresd Date 
LP1430: 840319 
PROC; E 
DCL 
1A, a 
SINCLUDE CUSTFILE(CUSTFMT,RECORD,PLANT_); 
ft SoBe eau ee eceee cee menee ee etane. oe ee eee oeteee et 7] 
/* PHYSICAL FILE: CUSTFILE.QTEMP */ 
/* FILE CREATION DATE: 87/11/30 */ 
/® RECORD FORMAT: CUSTFMT */ 
/* RECORD FORMAT SEQUENCE ID: 371E@@A681EA7 */ 
/* eSesde ro ciewenwe ee shb eb ess eek wee ew cd soe s esse SS eee es sesetekse x/ 
; 15 PLANT_CUSTNAME  CHAR(25), /* CUSTOMER NAME }f */ 
3 =—s«-15 PLANT_CUSTOMER_HOME_ADDRESS CHAR(25), 
/* CUSTOMER HOME ADDRESS J} = */ 
15 PLANT_CUSTOMER_BUSINESS ADDRESS CHAR(25), 
/* CUSTOMER BUSINESS ADDRESS */ 
15 PLANT_CUSTNO — PIC: '999999999R'; 
/* CUSTOMER NUMBER */ 
/* ODS - KEY FIELD fq */ 
DCL 
1 8, 
SINCLUDE CUSTFILE(CUSTFMT, KEY) :f§l 
]S. cedteueveda sic srueuantancasseie weswsteseestschecseseececwacuses */ 
/* PHYSICAL FILE: CUSTFILE.QTEMP ®/ 
/* FILE CREATION DATE: 87/11/30 */ 
/* RECORD FORMAT: CUSTFMT */ 
/* RECORD FORMAT SEQUENCE ID: 371EGQA681EA7 */ 
/® Sei eee eo tas See a eece mene eeobawedacoececececeoueedecesoocces x/ 
15 CUSTNO — PIC: '999999999R'; 
/* CUSTOMER NUMBER */ 
[= /* DDS - ASCENDING */ 
/* *UNSIGNED' KEY FIELD */ 
DCL FILE1015 FILE RECORD UPDATE SEQL KEYED ENV( INTERACTIVE); LP160560 
DCL 1 RFMT1, LP100590 
% INCLUDE FILE1015 (SFLREC,RECORD) ; 
/® dedcecoecteaemoone wesc ueceoceecuseee waboaeomecucecoecGseaca decaooecoce */ 
/* DEVICE FILE: FILE1015.QTEMP */ 
/* FILE CREATION DATE: 87/11/36 */ 
/* RECORD FORMAT: SFLREC ay 
/* RECORD FORMAT SEQUENCE ID: 68C100874B716 */ 
/* Mecem ee iemedow sd eeSececescdeood SéSSeeceeseee woe coccoceedeocoeeces x] 
/* INDICATORS FOR FORMAT SFLREC */ 
/* INDICATOR 01 CHANGE INDICATOR */ 
/* INDICATOR 02 CHANGE INDICATOR */ 
/* INDICATOR 03 */ 
/* Stee See ee eh See se eee ee eee ee Se eee ee ceoc eee eee */ 
15 NUMBER1 PIC '99R’, 
15 ALPHAL CHAR(16) ; 
DCL 1 RFMTO, 
%INCLUDE FILE1015 (SFLCTL,RECORD); §Ry 
/* eee eS ek See oe See Sh oe es eee ec ese x/ 
/* DEVICE FILE: FILE1015.QTEMP */ 
/* FILE CREATION DATE: 87/11/36 */ 


Figure 8-23 (Part 2 of 3). % INCLUDE Examples 
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‘Si 5728PL1 RO1l M6 880715 PL/I Source Listing QTEMP/LP1436 11/30/88 15:31:28 Page 3 
LP1430: 

Include SEQNBR STMT.SUBS BLK BN DO 8K. toc. Li cect ec ce Qe cc etn cede cc ete c cede cc cto ccc Se cc cteeccDeve stones emeeteee8 Date 
SFLCTL + 4600 /* RECORD FORMAT: SFLCTL * / 
SFLCTL + 560 /* RECORD FORMAT SEQUENCE ID: 6230713C3E414 #7 
SFLCTL + 600 f Pipe ee eras oes cee ec se sey enerieewet es oyae se */ 
SFLCTL + 700 /* INDICATORS FOR FORMAT SFLCTL * / 
SFLCTL + 800 /* INDICATOR 04 */ 
SFLCTL + 900 /* INDICATOR 05 */ 
SFLCTL + 1000 ] Btn ee eaen ase ee ease nase secs eee ase e oases ces aos eae es */ 
SFLCTL + 1100 6.1 1 1 14] 15 DUMMYDCL CHAR(@); /* NO FIELDS OF NEEDED TYPE */ 

1460 7 1 1 DCL 1 INDAREA, LP100730 

1500 %INCLUDE FILE1015(SFLREC,INOICATORS); FG 
SFLREC + 160 JR pase Pmaes tess eek Stoo eae Cee cre se tase anes eee Cee aesece */ 
SFLREC + 200 /* DEVICE FILE: FILE1015.QTEMP */ 
SFLREC + 300 /* FILE CREATION DATE: 87/11/30 x / 
SFLREC + 400 /* RECORD FORMAT: SFLREC */ 
SFLREC + 500 /* RECORD FORMAT SEQUENCE ID: 08C1008748716 */ 
SFLREC + 600 je Beeps tee sees ee eee ee eae umes osekee */ 
SFLREC + 700 7.1 1 1 16 15 INO1 PIC '9', /* CHANGE INDICATOR */ 
SFLREC + 800 7.2 1 1 15 IN62 PIC '9', /* CHANGE INDICATOR * / 

‘ SFLREC + 960 7.3 1 1 15 IN03 PIC '9', 

SFLREC + 1000 7.4 1 1 16 15 INO4_IN99 CHAR(96); /* UNDEFINED INDICATOR(S) */ 

1600 8 1 1 DCL 1 INDAREA2, LP100730 

1760 % INCLUDE FILE1015({SFLCTL, INDICATORS) ; 
SFLCTL + 100 JP Sheets peo eee sees se ee ee ot eae eee eset aes */ 
SFLCTL + 200 /* DEVICE FILE: FILE1015.QTEMP */ 
SFLCTL + 300 /* FILE CREATION DATE: 87/11/30 */ 
SFLCTL + 400 /* RECORD FORMAT: SFLCTL */ 
SFLCTL + 500 /* RECORD FORMAT SEQUENCE ID: 0230713C3E414 */ 
SFLCTL + 600 [Feo ae esas eee oo aoe ete ad oe ee ee a ea */ 
SFLCTL + 700 8.1 1 1 15 INQ1_INO3 CHAR(03), /* UNDEFINED INDICATOR(S) */ 
SFLCTL + 800 8.2 1 1 15 INO4 PIC '9', 
SFLCTL + 900 8.3 1 1 15 IN@5 PIC '9', 
SFLCTL + 1008 8.4 1 1 15 INO6_IN99 CHAR(94); /* UNDEFINED INDICATOR(S) * / 

_ 1800 9 1 1 DCL INDICATORS(99) CHAR(1) BASED(PTR), 

1900 9.1 1 1 PTR POINTER; 

2000 «3-10 11 DCL I BIN FIXED(15); 

2100 3s 11 1 1 PTR = ADDR(INDAREA); 

2200 23 12 1 1 DO I=1 TO 99; 

2300 = 13 111 INDICATORS(I) = '0'; 

2400S ss«14 111 END; 

2500 = «15 1 1 PTR = ADDR(INDAREA2) ; 

2600 16 11 DO I=1 TO 99; 

2700 = s«17 111 INDICATORS(I) = '@'; 

2800 = «18 111 END; 

2900 «36:19 1 1 OPEN FILE (FILE1015); LP100850 

3000 = -20 1 1 DO I=1 TO 5; 

3100 = 21 111 NUMBER1 = I; 

3200 39.22 111 ALPHA1 = 'XX'; 

3300 =. 23 111 WRITE FILE(FILE1015)FROM(RFMT1) KEYFROM(1I) 

3400 111 OPTIONS(RECORD ('SFLREC') 

3500 111 INDICATORS(INDAREA) ); 

3600 24 111 IF IN@3 = 1 THEN 

3700 111 INO3='0'; 

3800 =. 25 111 ELSE 


Figure 8-23 (Part 3 of 3). % INCLUDE Examples 


The source sequence field is set to 100 and is incremented by 100 with each 
line that follows. 


FAs The original line sequence numbers are resumed at the end of the generated 
statements. 


The date field is left blank on generated statements. The actual 
; %INCLUDE directive has a value put in the date field if it has been altered 
( in SEU since the source was first entered. 
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The prefix PLANT _ is specified as an option of the % INCLUDE directive. 


Each occurrence of a %INCLUDE directive generates line comments that 
identify the file name, format name, record format sequence identifier, and 
file creation date. 


The field name on the DDs is CUSTNAME. Because the prefix PLANT_ 
was specified as an option of the % INCLUDE directive, the generated name 
is PLANT_CUSTNAME. The default level number for each generated field 
is 15. 


The TEXT keyword was specified on the DDs with the parameter CUS- 
TOMER NAME. The parameter is therefore printed as a comment after the 
declaration. 


The field name on the DDs is CUSTADDRI1. Because the keyword ALIAS 
was specified in the DDs with the parameter 
CUSTOMER HOME ADDRESS, the ALIAS parameter is used as the var- 
lable name and the prefix PLANT _ 1s attached to it to generate the variable 
name PLANT CUSTOMER HOME ADDRESS. 


The keyword TEXT is also specified in the DDs with the parameter CUS- 
TOMER HOME ADDRESS. The TEXT parameter is listed as a comment 
in the generated staternent. 


A comment is generated indicating that CUSTNO is defined on the DDs as a 
key. 


KEY is specified as the element-type included from record format 
CUSTFMT. 


A comment is generated indicating that CUSTNO is specified on the DDs as 
a key that is unsigned and in ascending sequence. 


RECORD is specified as the element-type included from record format 
SFLCTL. Therefore, fields in the record that specify BOTH on the DDs are 
included in the generated statement. If INDARA is not specified on the 
DDS, indicators for which BOTH is specified on the DDs are also included in 
the generated statement. 


Record format SFLCTL has no fields for which BOTH is specified on the 
DDs. The generated structure therefore contains no data elements. The com- 
piler generates a character string DUMMYDCL with a length of zero. 


INDICATORS is specified as the element-type included from record format 
SFLREC. 


Indicators 1 to 3 are specified on the DDS, and are therefore declared in the 
generated text with PIC '9'as their attribute. Indicators 4-99 are not speci- 
fied on the DDS, and are therefore not declared in the generated text. Instead, 
a variable IN04_IN99 is declared in the generated text, and is given the attri- 
bute CHARACTER and a length of 96 bytes. 
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This chapter contains information on references and expressions, and their use in 
PL/I. 


An expression is a representation of a value. It can consist of constants, variables, 
and function references, along with operators or parentheses, or both. 


The syntax of expressions and references is shown in Figure 9-1 on page 9-2. 


A reference can be a scalar reference, which refers to a scalar data item, an array 
reference, which refers to an array, or a structure reference, which refers to a struc- 
ture. An expression that represents a scalar value is a scalar expression. The only 
C non-scalar expressions are array references and structure references. 


The syntax of many PL/I statements allows expressions. In this manual the term 
“expression” refers to a scalar expression except where stated to the contrary. 


The examples that follow illustrate the syntax of expressions and references. They 
use the following declarations: 


DECLARE BINFIXEDARRAY (10,10) BINARY FIXED (31), 
1 STRUCTURE1, 
5 DECFIXED1 DECIMAL FIXED (4,2), 
S 5 DECFIXED2 DECIMAL FIXED (4,2), 
1 STRUCTURE2(2), 
5 DECFIXED1 DECIMAL FIXED (4,2), 
5 DECFIXED2 DECIMAL FIXED (4,2), 
BINFIXED1 BINARY FIXED (15), 
BINFIXED2 BINARY FIXED (15), 
POINTER1 POINTER, 
ENTRYVAR ENTRY VARIABLE, 
ENTRYCON ENTRY; 


( | Here are some examples of expressions: 


BINFIXED 1 
A unary expression that is an elementary expression that is a reference that is a 
basic reference that is a name. 


BINFIXED1++«BINFIXED2 
An expression that contains a unary expression followed by an infix operator 
followed by a second unary expression. 


Because the expression contains an infix operator (the exponentiation operator 
xx), It is an operational expression. The unary expressions are operands. Oper- 
ators are discussed under “Delimiters” on page 4-3. Operational expressions are 
discussed under “Operational Expressions” on page 9-4. 
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expression 1s: 
unary-expression|infix-operator' unary-expression]... 
where unary-expression is: 
[prefix-operator’...]elementary-expression 
where elementary-expression is: 
(expression)|constant|reference 
where reference? is: 


[pointer-qualifier|basic-reference 
|(subscript-list)|[(argument-lisd[Q]] 


where pointer-qualifier* is: 
reference — > 

where subscript-list° is: 
expression|,expression]... 

where argument-list® is: 
[expression|,expression]...] 

where basic-reference’ is: 


|name.]...name 
Notes: 


‘Any of the operators shown in Figure 4-2 on page 4-4, except for the 4 oper- 
ator, can be used as an infix-operator, but . <, ~=, and — > are valid infix- 
operators. 

?Any of the operators +, -, — can be used as a prefix-operator. 

*The optional empty argument list is discussed under “CALL Statement” on 
page 14-7. 

*pointer-qualifier is discussed under “Based Variable Reference and Pointer 
Qualification” on page 5-20. 

*subscripts are discussed under “Subscripts” on page 5-2. 

Sarguments are discussed in Chapter 14, “Procedures, Subroutines, and 
Functions.” 

7Structure qualification (‘‘.”) is discussed under “Structure-Qualification” on 
page 5-5. 


Figure 9-1. Syntax of Expressions and References 
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-BINFIXED2 
A unary expression that is a prefix operator followed immediately by a basic 
reference. 


Because it contains the minus prefix operator, -, it is an operational expression; 
BINFIXED2 is the operand. The prefix operator specifies that the negative 
value of BINFIXED2 is used. 


BINFIXEDARRAY 
A basic reference. 


Because BINFIXEDARRAY refers to an array, it is an array reference. Arrays 
are discussed under “Using Arrays and the Dimension Attribute” on page 5-1. 


BINFIXEDARRAY(2,4) 
A reference that is a basic reference followed by a subscript list. 


BINFIXEDARRAY (2,4) ts a subscripted reference. 


A unary expression, an elementary expression, and a constant. 


BINFIXEDARRAY (2,4) + BINFIXED 1 
An operational expression (see “Operational Expressions” on page 9-4). 


(BINFIXEDARRAY (2,4) + BINFIXED1) « 2 
An operational expression (see “Operational Expressions”). 


The sequence of operations is discussed under “Priority of Operators” on 
page 9-15. 


POINTER! — > BINFIXEDARRAY(2,4) 
A pointer qualifier (POINTER1 — >), followed by a basic reference, followed 
by a subscript list. 


It is a pointer-qualified and subscripted reference. Pointer-qualifiers are dis- 
cussed under “Based Variable Reference and Pointer Qualification” on 
page 5-20. 


STRUCTURE1.DECFIXED1 
A basic reference which consists of a name, followed by a period, followed by a 
name. 


STRUCTUREI1.DECFIXED1 is a fully-qualified structure reference. Struc- 
tures are discussed under “‘Using Structures and Level Numbers” on page 5-3. 


STRUCTURE2.DECFIXED1(1) 
A basic reference followed by a subscript list. 


STRUCTURE2.DECFIXED1(1) is a fully-qualified and subscripted reference 
to a field of the first array element of STRUCTURE2. STRUCTURE? is an 
array of structures. Arrays of structures are discussed under “Arrays of 
Structures” on page 5-5. 


STRUCTURE]1.DECFIXED1 - STRUCTURE2.DECFIXED 1(1) 
An operational expression (see “Operational Expressions” on page 9-4). 


STRUCTURE1.DECFIXED1 / 4 
An operational expression. 
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BINFIXEDARRAY(2,4) « STRUCTURE2.DECFIXED2(2) 
An operational expression. 


ENTRYVAR = ENTRYCON 
An operational expression. 


The remainder of this chapter discusses expressions that consist of operators and 
operands; such expressions are also called operational expressions. 


Operational Expressions 


An operational expression is an expression that consists of one or more operations. 
An operation can be either a prefix operation, which consists of a prefix operator 
followed by an operand, or an infix operation, which consists of an infix operator 
between two operands. 


An operational expression can always be considered as a single operation. For 
example, the expression 


A+ Bx«C 


is an infix operation whose operator is +, whose first operand is A, and whose 
second operand is B « C. 


The operands and operator of an infix operation, or the operand and operator of a 
prefix operation, determine the attributes of the result of the operation. In this way, 
the attributes of the result of the entire operational expression can be determined. 


The operands of an operation must be scalar expressions. The operation itself is 
also a scalar expression. 


The operand(s) of an operation must be of the type required by the operator. For 
example, an arithmetic operator requires arithmetic operands. Therefore, before you 
use data as operands, you may have to convert them explicitly to the appropriate 
type, either by assigning them to a variable declared with the required attributes or, 
preferably, by means of the appropriate built-in function. 


If the types of the operands are correct, some implicit conversion may still be neces- 
sary. For example, the operands of most arithmetic operators are converted to their 
common base and scale before the operation is processed. The types of the oper- 
ands required by each operator and the conversions that will be processed implicitly 
are described below for each class of operations. 


The rest of this chapter describes the four classes of operations: arithmetic, bit, com- 
parison, and concatenation. 
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Arithmetic Operations 


The operands of an arithmetic operation must be arithmetic. 


You specify an arithmetic operation by one of the following operators: 
+ - * / ** 


The + (plus) and - (minus) operators can be either prefix or infix operators, whereas 
the « (multiplication), / (division), and «« (exponentiation) operators are infix oper- 
ators only. 


Data Conversion in Arithmetic Operations 


The two operands of an arithmetic operation may have different data attributes. 
They are converted as described below. 


Picture data operands are considered fixed-point decimal operands with a precision 
(p,q), which is derived from the picture specification. They are treated as fixed- 
point decimal operands. The result of an arithmetic operation is always in coded 
arithmetic form. 


Data conversion in arithmetic operations depends on if the operation is 
exponentiation: 


¢ Operations other than exponentiation. The operands are converted, as neces- 
sary, to the base and scale of the result, which is the common base and scale of 
the operands, as follows: 


— Ifthe bases of the two operands differ, the base of the result is binary. 


— Ifthe scales of the two operands differ, the scale of the result is floating- 
point. 


¢ Exponentiation. Three cases govern the data attributes of the result. The base, 
scale, and precision of the result depend on the significand and on the exponent, 
as shown in Figure 9-3 on page 9-8. 


Results of Arithmetic Operations 


After any necessary conversion of the operands, the arithmetic operation is proc- 
essed. 


The result of an operation must be floating-point, fixed-point binary with a zero 
scale factor, or fixed-point decimal with a non-negative scale factor. Therefore: 


¢ If one operand of the divide operator is fixed-point binary, the other must not 
be fixed-point. 


e If one operand of any infix operator, except exponentiation (*+), or of the 
MAX, MIN, MOD, or DIVIDE built-in functions is fixed-point binary, the 
other operand must not be fixed-point decimal or picture with a nonzero scale 
factor. 
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The precision of the result is determined from its base and scale, from the precision a 
of the operands after any necessary conversion, and from the operation. 


Figure 9-2 on page 9-7 describes the result of the two steps involved in evaluating 
an operation: converting the operands to the base and scale of the result, and calcu- 
lating the precision of the result. Figure 9-3 on page 9-8 shows the attributes of the 
result for the special cases of exponentiation noted in the right-hand column of 
Figure 9-2. 


For the following example, refer to Figure 9-2. If the first operand is fixed-point 
binary with precision (5) and the second operand is fixed-point-decimal with preci- 
sion (4), the result of multiplication is fixed-point binary with precision (21), which 
is calculated from the following: 


p= 1+ p,; + 1 + ceil(pz *3.32) 


where: J 


p is the number-of-digits of the result 
p, _ is the number-of-digits of the first operand 


p, 1s the number-of-digits of the second operand. 


Now refer to Figure 9-2 on page 9-7 and Figure 9-3 on page 9-8. If the same 
operands are used in an exponentiation, the result is floating-point binary with pre- 
cision (5) from the first operand. In this example, case C applies. 


With the DIVIDE built-in function, you can override the implementation precision 
rules for division. 


In Figure 9-2, p,; and q,, and p, and q, are the converted precisions of the oper- 
ands, which have the base and scale of the result. (“ceil” means round the argument 
up to the next integer.) Figure 9-4 on page 9-8 is a table of ceil(n+3.32) and 
ceil(n/3.32) values.! 


The result of fixed-point division has the maximum implementation-defined number S) 
of digits, often with a large scale factor that may deny sufficient place for the integer 

part and therefore result in the overflow or truncation of the value. For example, 
the expression: 


25+1/3 
is evaluated as follows: 


1. The division operation 1/3 is processed first. (The sequence of operations is 
discussed under “Priority of Operators” on page 9-15.) This gives the interme- 
diate result 0.33333333333333, which has the precision (15,14). Constants have 
the precision with which they are written. 


1 The number 3.32 is the approximate number of binary digits per decimal digit. 
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2. The integer 25, which has the precision (2,0), is added to the intermediate result, 
resulting in a precision of (15,14). The fixedoverflow condition is raised, and 
the result is undefined. 


The following expression avoids truncation: 
25+01/3 


This expression is evaluated as follows: 


1. The division operation is processed, giving the intermediate result 
00.3333333333333, which has the precision (15,13). 


2. The integer 25 and the intermediate result are added, giving 25.3333333333333. 


You could alternatively use the DIVIDE built-in function: 
25+DIVIDE(1,3, 15, 13) 


See “DIVIDE(x,y,p[,q])” on page 15-10. 


Attributes of the Result Attributes of the Addition or Subtraction Multiplication Division 
First Operand Second Operand for Addition, Subtraction, Intermediate Result Precision” Pracision? Precision? 
Multiplication, or Division for Exponentiation 
FIXED DECIMAL (p,. q,) FLOAT DECIMAL (p) unless | p=1+max (p,—q,,p,-Qz)+q | P7M™N(15.P, +Py* 1) p=15 
or FIXED DECIMAL (p,q) special case A or C applies? q=max (q,.92} q=15—((p, —q,)+q,} 
PICTURE’ & p=max (p,,q,) : 
FIXED DECIMAL (p,.q,) FLOAT BINARY (p) unless 
or FIXED BINARY (p,)* 5 FIXED BINARY (p) special case C applies? p= 1+max (ceil (p, *3.32)+1,p2} | p=ceil (p, *3.32)+p, +2 
PICTURE! p=max (ceil (p, * 3.32) ,p2) 


FLOAT DECIMAL (p,) FLOAT DECIMAL (p) FLOAT DECIMAL (p) p=max (p,,p2) 
p= max (p, ,p2) 

FLOAT BINARY (p,) FLOAT BINARY (p) FLOAT BINARY (p) p= max (ceil (p, °3.32),p,) 
p=max (ceil (p, *3.32),p,) 


FIXED DECIMAL (p,.q2) FLOAT BINARY (p) unless 
or FIXED BINARY (p) special case A or C applies? p=max (p, ceil (p.*3.32)+1)+1| p=p, tceil (p,*3.32)+2 
PICTURE’ p= max (ceil (p, * 3.32) pz) 
FLOAT BINARY (p) unless 
FIXED BINARY (p,) FIXED BINARY (p,) 5 FIXED BINARY (p) special case C applies? p=1+max (p,,pz) p=p, +p2+1 
p=max (p, ,p2) 


FLOAT DECIMAL (p,) FLOAT BINARY (p) FLOAT BINARY (p) p= max (p, , ceil (pz ° 3.32) ) 
p=max (p, ,ceil (p, °3.32)) 

FLOAT BINARY (p,) FLOAT BINARY {p) FLOAT BINARY (p) p=max (p,,P2) 
p=max (p,,82) 


FIXED DECIMAL (p, :Q2) rosr onc oh FLOAT DECIMAL (p) unless 
or FLOAT DECIMAL (p) special case C applies? p=max (p, ,pz) 
PICTURE! p=max (p; ,p2) 
FLOAT BINARY (p) unless. 
FLOAT DECIMAL (p,} FIXED BINARY (p,) FLOAT BINARY (p) special case C applies? p=max (ceil (p, * 3.32) ,.p.) 
p=max (ceil (p, *3.32),p2) 


FLOAT DECIMAL (p,) FLOAT DECIMAL (p) FLOAT DECIMAL (p) p=max (p,.P2) 
p=max (p, .p2) 

FLOAT BINARY (p,) FLOAT BINARY (p) FLOAT BINARY (p) p= max (ceil (p, ° 3.32), p2) 
p=max (ceil (p, *3.32),p.) 


FIXED DECIMAL (p,,q,} FLOAT BINARY (p) unless 

or FLOAT BINARY (p) special case C applies? p=max (p, ,ceil (p. ° 3.32) ) 

PICTURE! p=max (p, ceil (pz ° 3.32) ) 
FLOAT BINARY (p) unless 

FLOAT BINARY (p,} FIXED BINARY (p,) FLOAT BINARY {(p) special case C applies? p=max (p,,p,) 

p=max (p, pz} 

FLOAT DECIMAL (p,) FLOAT BINARY (p) FLOAT BINARY (p) p=max (p, ceil (p> * 3,32) } 
p=max (p, ,ceil (pz ° 3.32) ) 


FLOAT BINARY (p.) FLOAT BINARY (p) FLOAT BINARY (p) p=max (p,.p2) 
p=max (p, pz) 


Figure 9-2. Results of Arithmetic Operations 
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Picture data is fixed-point decimal. Its precision is derived 
from the PICTURE specification. 
“Special cases of exponentiation are described in Figure 9-3. 
3The calculations of precisions must not exceed the 
implementation maximums: 

FIXED DECIMAL = 15 

FIXED BINARY = 31 

FLOAT DECIMAL = 16 

FLOAT BINARY = 33 
*Except in exponentiation, the scale factor must be zero. 
>The result of division is an integer: fractional digits are lost. 
°The result of division must have a non-negative scale-factor. 


ceil(x) means the smallest integer greater than or equal to x. 
max(x,y) means the greater of x and y. 
min(x,y) means the smaller of x and y. 


First Operand Second Operand Attributes of Result 


FIXED DECIMAL Integer Constant FIXED DECIMAL (p, q) 

(p1, q1) with value n>0 [provided ps15] 
p=(pi1 + 1) *exp - 1 
q=qi * n 


FIXED BINARY Integer Constant FIXED BINARY (p) 
with value n>0 [provided ps31] 
p=(pi1 + 1) * exp - 1 


FLOAT (p12) FIXED (pz, 0) FLOAT (p) with base 
FIXED DECIMAL or PICTURE of first operand 
(p1, qi) if without 

neither case fractional part 

A or case B p=max (pi, p2) 


1 Tf first operand = 0 and second operand > 0, the result is 0; 
if first operand = © and second operand s 0, the ERROR condition 
is raised; 
if first operand < 0 and second operand is not an integer, the 
ERROR condition is raised. 


Figure 9-3. Special Cases for Exponentiation 
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)n | ceil(n*3.32) | n —_| ceil(n/3.32) 
4 1-3 


l 
2 
3 
4 
5 
6 
7 
8 
9 


Figure 9-4. Table of Ceil Values 


The operands of a bit operation must be bit strings. If the operands of an infix 
operation differ in length, the shorter operand is padded on the night with zeros. 


You specify a bit operation by one of the following operators: 
~ & | 


You can use the — operator (‘‘not”’) only as a prefix operator, the & (“and”) and | 
(“or’’) operators only as infix operators. 


The result of a bit operation is a bit value equal in length to the longer operand. 


Bit operations are processed bit-by-bit, the operators having the same function as in 
boolean algebra. The results are as follows: 


= The bits are reversed: '1'B becomes '0'B and '0'B becomes '1'B. 


& If both corresponding bits are '1'B, the result is '1'B; otherwise, the 
result is '0'B. 


| If both corresponding bits are '0'B, the result is '0'B; otherwise, the 
result is '1'B. 
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The following table shows the result for each bit position for each of the operators: 


The following examples use the following operand values: 
Operand Value 
ABIT '010111'B 
BBIT 'W11111'B 
CBIT '110'B 


The following operators produce the following results: 


Operation Results 
—ABIT '101000'B 
—CBIT '001'B 
CBIT & BBIT '110000'B 
ABIT | BBIT '111111'B 
CBIT | BBIT '111111'B 
ABIT | (=CBIT) '1'B. 


=((=CBIT)|(— BBIT)) '110111'B 


Due to the padding required for CBIT, the operations CBIT & BBIT and 
—=((=CBIT)|(—BBIT)) are not equivalent. 


Comparison Operations 


Both operands of a comparison operator must be arithmetic, or both must be char- 
acter, or both must be bit, or they must both be of the same program control data 
type. Comparisons of entry, file, pointer, or label data can use only the = or 4 = 
operators. 


You specify a comparison operation by one of the following operators: 


Operator Meaning 


< less than 

i< not less than 

<= less than or equal to 

= equal to 

= not equal to 

>= greater than or equal to 
> greater than 

> not greater than 
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Comparisons of problem data can be: 


¢ Arithmetic, which involves the comparison of signed numeric values. If the 
operands differ in base or scale, they are converted to their common base and 
scale, as described under “Data Conversion in Arithmetic Operations” on 
page 9-5. Picture data operands are considered fixed-point decimal. 


If one operand is fixed-point binary, the other operand must not be fixed-point 
decimal or pictured with a nonzero scale-factor. 


e Character, which involves left-to-right, character-by-character comparison 
according to the collating sequence. Where the lengths of the operands differ, 
the shorter is padded on the right with blanks. 


e Bit, which involves left-to-nght, bit-by-bit comparison of binary digits. The 
shorter is padded on the right with zeros. 


Comparisons of program control data are equal when: 
e File operands represent the same file constant. 
¢ Label operands refer to the same statement in the same block activation. 
e Pointer operands have the same value. 
¢ Entry operands refer to the same entry name and, for internal entry constants, 


their values refer to the same block activation. 


The result of a comparison operation is a bit value of length 1; the value is '1'B if 
the relationship is true, or '0'B if the relationship is false. 


An example of a comparison operation in an IF statement is: 


IF A=B 
THEN action~-if-true 
ELSE action-if-false 


The evaluation of the expression A = B yields either '1'B (true) or '0'B (false); 
the action-if-true or action-if-false will be taken accordingly. 


In the assignment statement 
X=A<B; 


the value '1'B would be assigned to X if A were less than B; otherwise, the value 
'0'B would be assigned. 


In the following example, the value of CBIT is '110111'B and FFID is S: 
SUBSTR(CBIT,1,1) | (FFID=5) 


The result of FFID=5 is '1'B, as is the result of SUBSTR(CBIT, 1,1). The result 
of the “or” operation is therefore '1'B. If this expression appears in an IF state- 
ment, the length of the first operand must be 1. 
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Table for Comparison Operations 


Figure 9-5 on page 9-13 shows the attributes to which the two operands of a com- 
parison operation are converted before they are compared. These conversions are 
derived from the rules given on the preceding pages. (Ceil values are given in 
Figure 9-4 on page 9-9.) 


Find the row in Figure 9-5 that corresponds to the two operands in the expression 
evaluated. The first column refers to the first operand and the second to the second 
operand. The third and fourth columns give the attributes of the intermediate 
targets of the first and second operands, respectively, after any necessary conversion. 


For example: 


DECLARE ITEM PICTURE '99999', 
STANDARD FIXED BINARY(15); 
IF ITEM-=STANDARD THEN DO; 


In Figure 9-5, the entries in the third and fourth columns that correspond to a first 
operand with the PICTURE attribute and a second operand with the attributes 
FIXED BINARY are FIXED BINARY (1 + ceil(p, * 3.32)). This indicates that 
ITEM is converted to coded arithmetic form with the first set of attributes and that 
STANDARD is not converted. The precision (p,) is derived from the picture spec- 
ification and (p,) from FIXED BINARY (15) respectively. 


The tables indicate that ITEM will be converted to FIXED BINARY (18) and then 


compared algebraically with STANDARD), whose attributes remain FIXED 
BINARY (15). 
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First Operand Second Operand 
FIXED FIXED DECIMAL FIXED DECIMAL 
DECIMAL (pe, qz)?? (pr, q1) (pz, qz) 


PICTURE ! FIXED BINARY (p2) FIXED BINARY FIXED BINARY (pz) 
FLOAT DECIMAL (pz) | FLOAT DECIMAL (p:) FLOAT DECIMAL (pa) 


FLOAT BINARY (p2) FLOAT BINARY (p1) FLOAT BINARY (p2) 
(l+ceil (pia *3.32)) 


FIXED FIXED DECIMAL FIXED BINARY (p:) FIXED BINARY 
( BINARY (pz) (p2, q2) (l+cei] (p2 *3.32)) 


PICTURE 2 FIXED BINARY (pz) 
FIXED BINARY (p2) 


FLOAT DECIMAL (pz) | FLOAT BINARY FLOAT BINARY 
(ceil (pz *3.32)) 


FLOAT BINARY (pz) 


FLOAT BINARY (p2) 


FLOAT FIXED DECIMAL FLOAT DECIMAL (pz) FLOAT DECIMAL (p2) 
DECIMAL (p:) (pz, q2) 


PICTURE ! 
FIXED BINARY (pz) | FLOAT BINARY FLOAT BINARY (p2) 
FLOAT DECIMAL (pz) | FLOAT DECIMAL (p1) FLOAT DECIMAL (pa) 


FLOAT BINARY (p2) FLOAT BINARY FLOAT BINARY (pz) 
ceil (pi *3.32)) 


FLOAT FIXED DECIMAL FLOAT BINARY (p1) FLOAT BINARY 
: BINARY (p1) (pz, gz) (ceil (p2 *3.32)) 


PICTURE 2 FLOAT BINARY (pz) 

FIXED BINARY (pa) FLOAT BINARY 
(ceil (p2 *3.32)) 

FLOAT DECIMAL (p2) 

FLOAT BINARY (p2) FLOAT BINARY (p2) 


CHARACTER CHARACTER (n2) CHARACTER CHARACTER 
(m1) (max(ni, n2)) (max (ni, n2)) 


BIT (m:) BIT (max (ni, nz2)) BIT (max (ni, n2)) 


1 If you specify a scale factor, it must be equal to zero. 
2 Picture data is fixed point decimal. Its precision is derived from 
the PICTURE specification. 


ceil (x) is the smallest integer that is greater than or equal to x. 
( max (x,y) is the greater of x and y. 
Figure 9-5. Results of Comparison Operations 
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Concatenation Operations 
Concatenation can be processed only upon strings. Both strings must be character 
or both must be bit. 


You specify a concatenation operation by the concatenation operator 


It signifies that the operands are to be joined in such a way that the last character or 
bit of the operand to the left immediately precedes the first character or bit of the 
operand to the nght with no intervening bits or characters. 


The result of concatenating two character strings is a character string, and the result 
of concatenating two bit strings is a bit string; the length of the resulting string is the 
sum of the lengths of the two operands. 


For example, concatenation operations using the following operands and values: 


Operand Value 


ABIT '010111'B 
BBIT '101'B 
CCHAR 'XY,Z' 
DCHAR'  'AA/BB' 


produce the following results: 


Operation Results 


ABIT||BBIT '010111101'B 
ABIT||ABIT||BBIT 010111010111101'B 
CCHAR||DCHAR ‘'XY,ZAA/BB' 
DCHAR||CCHAR _‘'AA/BBXY,Z! 


Combinations of Operations 
You can combine different operations within the same expression, provided you 
observe the rules for the data types of the operands for each operator. The result of 
each embedded operation is used as an operand of a further operation. For 
example: 


DECLARE RESULT BIT (3) ALIGNED, 
AFID FIXED DECIMAL (1) STATIC INITIAL (2), 
BFIB FIXED BINARY (3) STATIC INITIAL (6), 
CFLOD FLOAT DECIMAL (2) STATIC INITIAL (32000), 
DBIT BIT (4) ALIGNED STATIC INITIAL ('1101'B); 

AFID = 2; 

BFIB = 6; 

CFLOD = 32000; 

DBIT = '1101'B; 

RESULT = AFID + BFIB < CFLOD & DBIT; 


The operands are converted, as required, before each operation is processed in the 
following order: 
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1. The decimal value of AFID is converted to a binary value of 2. 


2. The value of BFIB is added to the converted value of AFID and stored in a 
halfword binary fixed intermediate result, which therefore has a value of 8. 


3. CFLOD and the fixed-point binary result of AFID + BFIB are converted to 
floating-point binary, and the intermediate results are compared. 


4. The result of the comparison, a bit value of length 1 with a value of '1'is 
extended with zeros to the length of the bit variable DBIT, and the “and” oper- 
ation is processed. 


5. The result of the “and” operation is a bit value of length 4 with a value of 
'1000'B. It is assigned to RESULT without conversion, but with truncation 
on the right; the final value is therefore '100'B. 


Although in this example the expression is evaluated operation-by-operation, from 


left to nght, the order of evaluation is in fact determined by the priority of the oper- 
ators. 


Priority of Operators 
The order in which operations in an expression are processed is based on the pri- 
ority of the operators involved: the operation with the operator of the highest pri- 


ority is processed first, that with the operator of the lowest priority last. The 
priority of the operators in the evaluation of expressions is shown in Figure 9-6. 


ok 


arithmetic 


arithmetic 


arithmetic 
concatenation 


comparison 


Figure 9-6. Priority of Operators 


The operators are listed in order of priority, 1 being the highest priority and 7 the 
lowest. Operators in the same group have the same priority. For example, the 
exponentiation operator ** has the same priority as the prefix +, prefix -, and -— 
operators. 
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If two or more operators of priority 1 appear in an expression, their order of evalu- 
ation is from right to left; that is, the nghtmost exponentiation or prefix operator is 
applied first, the next rightmost next, and so on. 


For all other operators, if two or more operators of the same priority appear in an 
expression, their order of evaluation is from left to right. 


For example: 


DECLARE RESULT FIXED DECIMAL (7,1), 
AFID FIXED DECIMAL (1) 
BFIB FIXED BINARY (3), 
CFLOD FLOAT DECIMAL (2) 
DPIC PICTURE '999V9'; 


RESULT = AFID * BFIB * CFLOD + DPIC; 


The operations in this expression are processed from left to right, because multipli- 
cation has a higher priority than addition, and the order of evaluation of the two 
multiplications is from left to nght. 


The order of evaluation (and, consequently, the result) of an expression can be 
changed by parentheses. Expressions enclosed in parentheses are evaluated first, 
starting with the innermost parenthesized expression, before they are considered in 
relation to surrounding operators. 


The expression above is evaluated as if its operations were parenthesized as follows: 
((AFID * BFIB) * CFLOD) + DPIC 


The following expression 
AFID * (BFIB * (CFLOD + DPIC)) 


is evaluated as follows. The value of DPIC would be converted to floating-point 
decimal and added to the value of CFLOD, yielding a floating-point decimal result 
(result_1). The value of BFIB and result_1 would then be converted to floating- 
point binary and multiplied, yielding a floating-point binary result (result_2). The 
value of AFID would then be converted to floating-point binary and multiplied by 
result 2, yielding a floating-point binary result. 


For parenthesized expressions within expressions, PL/I specifies only that the paren- 
thesized expressions will be evaluated before any unparenthesized expression. It 
does not specify the order in which the parenthesized expressions will be evaluated. 
For example: 


(AFID + BFIB) * (CFLOD - DPIC) 
In this case, the parenthesized addition and subtraction will be done before the 


unparenthesized multiplication. PL/I does not specify if (AFID + BFIB) or 
(CFLOD - DPIC) will be evaluated first. 
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While a program is running, certain exceptional situations, called conditions, may be 
detected. When a condition is detected, it is said to be raised. These conditions 
may be errors, such as overflow, or they may be expected situations, such as the end 
of an input file. 


When a condition is raised, the action established for it is run. For each condition 
listed under ‘‘Specifiable Conditions in ON and SIGNAL Statements,” you can 
either use the ON statement to establish the action taken or rely on the implicit 
action defined for it. 


For each condition, there are condition codes that correspond to the different situ- 
ations in which the condition can be raised. You can obtain the condition code and 
other information associated with a raised condition by using the condition-handling 
built-in functions in an on-unit. 


In certain cases, conditions may be detected while compiling your program. These 
are diagnosed and are not raised when the program is run. 


The following sections summarize the conditions for which ON and SIGNAL state- 
ments can be written, as well as other conditions that may be raised. Each condi- 
tion is discussed, together with its implicit action and condition codes, in 

Appendix D, “Conditions and Condition Codes.” 


Specifiable Conditions in ON and SIGNAL Statements 


Two groups of conditions can be specified in an ON or SIGNAL statement: the 
ERROR condition and the input/output conditions. 


(file_constant) 


Abbreviation: UNDF for UNDEFINEDFILE 


The ERROR condition is raised when any one of several errors is detected. It is 
also raised as the implicit action for a number of other conditions, such as the con- 
version condition. You can find out which condition was raised, by using the 
ONCODE built-in function in an on-unit. (On-units are discussed under “ON 
Statement” on page 10-2.) 
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Input/output conditions always relate to a particular file. For example, there is an 
ENDFILE condition for each file used in the program. 


Unspecifiable Conditions 


Conditions that will be detected, but for which you cannot write ON or SIGNAL 
statements, are: 


conversion 
fixedoverflow 
overflow 
record(file-constant) 
storage 

stringsize 

underflow 
zerodivide 


When one of these conditions 1s detected, the implicit action (see below) is taken. 


Established Action 


Implicit Action 


ON Statement 


The established action for a condition is the action taken if the condition is raised. 
This is either the implicit action or the action specified in an ON statement for the 
condition. 


Each condition has an implicit action, which is established when the program is acti- 
vated and remains established unless overridden by processing an ON statement for 
the same condition (see “Scope of the Established Action” on page 10-4). 


The implicit action for most conditions is to issue a message and raise the ERROR 
condition. The implicit action for each condition is given in Appendix D, “Condi- 
tions and Condition Codes.” 


The ON statement explicitly establishes the action taken when a condition is raised. 
The action established by the ON statement overrides or suspends any currently 
established action unless overridden by a further ON statement for the same condi- 
tion, or until the block it was processed in ends (see “Scope of the Established 
Action” on page 10-4). The ON statement can also be used to reestablish the 
implicit action. 


>>—ON—conditi ee 
on_unit SNAP 


condition 
Any of the conditions given under “Specifiable Conditions in ON and SIGNAL 
Statements” on page 10-1. 
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| IBM Extension | 


SNAP 
Transmits diagnostic data to the AS/400 dump file QPPGMDMP. The data 
includes: 


e The current statement number. 
¢ A list of currently active blocks and on-units, listed in order of calling. 


SYSTEM 
Specifies that the implicit action is established for the condition. 


ees End of IBM Extension es ll 


on_unit 
Specifies the action established for the condition. It can be either an unlabeled 
statement (including a null statement), or an unlabeled begin-block. If it is an 
unlabeled statement, the following statements are not allowed: BEGIN, 
DECLARE, DO, END, IF, ITERATE, LEAVE, PROCEDURE, RETURN, 
or SELECT. If it is a begin-block, a RETURN statement can appear only in a 
procedure nested within the block. 


Because the on-unit itself requires a semicolon, no semicolon is shown for the 
on-unit in the syntax. 


Up to 49 on-units can be concurrently active in any block. An external proce- 
dure can contain up to 254 on-units. 


An on-unit is treated as a procedure without parameters that is internal to the block 
in which it appears. Therefore, any names referenced in an on-unit are those known 
in the block in which the ON statement was processed, rather than in the block in 
which the condition was raised. 


Running an On-Unit 
An on-unit runs when the specified condition is raised, not when the ON statement 
is processed. 


An on-unit ends normally by returning control to the block from which the on-unit 
was entered. Control will return to the statement immediately after the statement 
that raised the condition if the on-unit ends normally. 

Running an on-unit may be ended abnormally by a GO TO statement that transfers 
control out of the on-unit, which allows program processing to continue, or by a 
STOP statement, which ends the run unit. 

The point to which control normally returns depends on the condition. Control 
may return to the point immediately following the poimt at which the condition was 
raised or to the statement following the one in which the condition was raised. 


The effect of a null statement on-unit is to process normal return from the on-unit. 


If an ERROR on-unit ends normally, the program will end abnormally. 
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For more information about on-units and condition handling, see 
Appendix D, “Conditions and Condition Codes.” 


Scope of the Established Action 
The established action remains in effect throughout the block in which the ON 
statement was processed and throughout all dynamically descendant blocks, unless it 
is overridden by an ON statement for the same condition or until the block in 
which the ON statement was processed ends. 


When another ON statement for the same condition is processed, the established 
action 1s affected as follows: 


¢ Ifthe block that contains the new ON statement is a dynamic descendant of the 
block that contains the earlier ON statement, the action established by the 
earlier ON statement is suspended. 


When control returns to the block that contains the earlier ON statement, all 
actions that were current immediately before its suspension are reestablished. 
Therefore, no subroutine can change the established action for its calling block. 


¢ If both ON statements are processed in the same block activation, the earlier 
ON statement is overridden. The earlier action can be reestablished only by 
processing an appropriate ON statement. 


Scope of Values of Condition Handling Built-In Functions 
The value of a condition handling built-in function is set when an on-unit for the 
corresponding condition is entered. This is described separately for each of the con- 
dition handling built-in functions (see Chapter 15, “Built-In Functions, Subrou- 
tines, and Pseudovariables”). The value remains in effect throughout the processing 
of that on-unit and its dynamic descendants, unless it is temporarily overridden 
when a second on-unit for a condition specific to the function is entered. If the 
second on-unit ends, the values that were in effect before it was entered are rein- 
stated. 


SIGNAL Statement 


The SIGNAL statement raises a specified condition. It simulates the occurrence of 
the condition and forces the processing of the established action. 


b>—S IGNAL——condition; >< 


condition 
Any of the conditions given under “Specifiable Conditions in ON and SIGNAL 
Statements” on page 10-1. 
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Example of Use of Conditions 


SIGNAL STATEMENT 


The subroutine shown in the example below illustrates the use of the ON statement 
and the SIGNAL statement. It reads records from a file SEQFILE. Each record 
consists of two values that are used to process the second file INFILE. 


5728PL1 RO1 M66 886715 PL/I Source Listing 
LP1431: PROCEDURE; 


We, es ce Le ean Pees Cake Pe hie Seve Ot es 


PLITST/LP1431 


Include SEQNBR STMT.SUBS BLK BN DO 


ie headetiaas Fess 


11/38/87 14:51:69 Page 2 
PUBQA168 
stewie OewecteseedePeetice.8 Date 


160 1 LP1431: PROCEDURE; PUBO9169 850169 
200 PUBG0170 
300 /* FILE DECLARATIONS */ PUBO0180 
480 2 1 1 DECLARE PUBO0190 
500 1 1 INFILE FILE RECORD INTERNAL SEQUENTIAL KEYED INPUT PUBOO208 841113 
600 1 1 ENV(CONSECUTIVE), 841113 
700 2.1 1 1 SEQFILE FILE RECORD INTERNAL SEQUENTIAL INPUT ENV(CONSECUTIVE), 841113 
800 2.2 1 1 SYSPRINT FILE STREAM OUTPUT PRINT, 841114 
900 2.3 1 1 CALC_PROC EXTERNAL ENTRY; 841114 
1000 PUB0O220 
1100 /* RECORD DECLARATIONS */ PUBO0230 
1200 3 1 1 DECLARE PUBOO240 
1300 1 1 1 RELATIVE_RECORD, PUBQ0260 841107 
1406 3.1 1 1 2 REL_WEEK PICTURE '99', PUBQO280 841107 
1500 3.2 1 1 2 REL_UNIT_SALES PICTURE '$999999'; PUBQO298 841113 
1600 841107 
1780 4 1 1 DECLARE 841107 
1800 1 1 1 INPUT_RECORD, 841107 
1906 4.1 1 1 2 START_WEEK BINARY FIXED(15), 841107 
2000 4.2 1 1 2 NUMB_WEEKS BINARY FIXED(15); 841107 
2100 PUBQ0348 
2200 /* PROGRAM FLAGS */ PUB08356 
2300 5 1 1 DECLARE PUB00360 
2400 11 1 BIT_FLAGS STATIC, PUB00370 
2500 5.1 1 1 2 MORE_RECORDS BIT(1) ALIGNED, PUBQ0380 
2600 5.2 1 1 2 ERR_KEY BIT(1) ALIGNED, 841113 
2700 5.3 1 1 2 NO BIT(1) ALIGNED INIT('O'B), PUB90390 
2800 5.4 1 1 2 YES BIT(1) ALIGNED INIT('1'B); PUBO0400 
2900 PUB004 10 
3000 /* PROGRAM VARIABLES */ PUBO0420 
3100 6 1 DECLARE PUBO0430 
3200 1 1 KEY_DATA BINARY FIXED(15), PUBOQ0440 841108 
3300 6.1 sae | ONCODE BUILTIN; 841108 
3400 841113 
3500 PUB00460 
3600 /* MAIN PROGRAM */ PUBQ0560 841113 
3706 7 | fl ON ENDFILE(SEQFILE) PUB00470 841113 
3800 1 1 MORE_RECORDS = NO; PUBO0480 
3900 PUBO0550 
4000 /* ESTABLISH ACTION FOR ERROR IN DIST */ 841113 
4100 8 1 1 aI ON ERROR BEGIN; 841107 
4200 9 3 2 ON ERROR SYSTEM; 841107 
4300 10 3 2 IF ERR_KEY = YES THEN 841113 
4400 32 DO; 841113 
4500 11 os 2 '] PUT FILE(SYSPRINT) SKIP EDIT('INVALID START WEEK:', START_WEEK) 841113 
4600 3-32. 2 (A,F(3)); 841113 
4700 12 3 2 1 GOTO END_PROC1; 841113 
4800 13 BS Seed END; 841113 
4900 14 3 2 ELSE DO; 841113 
5000 15 3.2 1 PUT FILE(SYSPRINT) SKIP 841113 
5100 3 2 1 EDIT('ERROR IN PROCESSING PROCEDURE: DIST')(A); 841113 
5200 16 3 2 1 GOTO END_PROC1; 841113 
5300 17 3 2 1 END; 841113 


Figure 10-1 (Part 1 of 2). Use of the ON and SIGNAL Statements 
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PL/I Source Listing 
LP1431: PROCEDURE; 


XE, Pee Be 


E 


END; 


/* BEGIN */ 


MORE_RECORDS = YES; 


ERR_ 


OPEN 
FI 
OPEN 
Fl 


READ FILE (SEQFILE) INTO (INPUT_RECORD) ; 


KEY = NO; 


LE (SEQFILE); 


LE (INFILE); 


PLITST/LP1431 


/* INPUT 


/* INPUT 


DO WHILE(MORE_RECORDS); 


IF START_WEEK <1 | START_WEEK >52 THEN 


DO; 

ERR_KEY = YES; 
SIGNAL ERROR; 
END; 


CALL RANDOM; 


READ FILE (SEQFILE) INTO (INPUT_RECORD) ; 


END; 


/* DO WHILE */ 


RANDOM: PROCEDURE; 


/* ESTABLISH ACTION FOR ERROR IN RANDOM */ 


ON 


/* ESTABLISH ACTION FOR KEY IN RANDOM */ 


ERROR BEGIN; 


OH ERROR SYSTEM; 


PUT FILE(SYSPRINT) SKIP 
EDIT('ERROR IN PROCESSING PROCEDURE: RANDOM') (A); 


GOTO END_PROC1; 


END; /* BEGIN */ 


ON KEV(INFILE) BEGIN; 


ON ERROR SYSTEM; 


IF ONCODE = 51 THEN 


DO; 


PUT FILE(SYSPRINT) SKIP 
EDIT('SPECIFIED KEY NOT FOUND IN FILE INFILE, KEY=',KEY_DATA) 


(A,A); 
END; 
ELSE 


PUT FILE(SYSPRINT) SKIP 


*/ 
*/ 


11/36/88 14:51:69 


EDIT('ERROR ON KEY SPECIFIED, KEY=’,KEY_DATA)(A,A); 
END; /* BEGIN */ 


DO KEY_DATA = START_WEEK TO (START_WEEK + NUMB WEEKS-1) BY 1; 
READ FILE (INFILE) INTO (RELATIVE_RECORD) KEY (KEY_DATA); 


END; /* DO LOOP */ 


END 


END_ 


CALL CALC_PROC; 


RANDOM; 


PROC1: 


CLOSE 


FILE (SEQFILE); 


CLOSE 


FILE (INFILE); 


END LP1431; 


Figure 10-1 (Part 2 of 2). Use of the ON and SIGNAL Statements 
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841113 
841167 
841107 
PUBGE576 
841113 
PUBO6580 
PUBGO590 841167 
PUBO0668 841113 
841107 
PUBQ0606 841113 
841113 
PUB88718 841113 
PUBG658 
841167 
841113 
841113 
841113 
841113 
841113 
PUB@068E 841107 
PUB66710 841113 
PUB86720 
PUB66730 
PUB80780 
PUBG0796 
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841107 
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841113 
PUBGO500 841113 
PUBO@510 841107 
PUBQ0528 841107 
PUBQ0538 841167 
841107 
841113 
841113 
841107 
841167 
841107 
841107 
PUB@O540 841107 
841107 
841113 
PUB@8880 841113 
841113 
PUB8G840 841107 
841107 
PUBO8850 
PUBGO860 
841167 
PUB60749 841107 
PUB68750 841113 
PUB00760 841107 
PUBGO778 841113 
PUBO1070 
PUBO1086 850109 


The ON ENDFILE(SEQFILE) statement establishes the action taken when 
the end of the input file SEQFILE is reached. The flag MORE RECORDS 
is set to NO so that processing of the file will end. Control is then trans- 


2 


2 


SIGNAL STATEMENT 


ferred to the statement immediately following the READ that raised the 
ENDFILE. 


The ON ERROR statement establishes the action taken when an error is 
raised during processing of the DIST procedure. If the flag ERR_KEY is 
equal to YES, which means that the error is raised by the SIGNAL state- 
ment, the appropriate error message will be produced. Control then passes 
to the END_PROC1 label. Any error raised within the on-unit is dealt with 
by the implicit action, due to the ON ERROR SYSTEM statement. 


Processing begins by setting the initial state of the flags and opening the files. 


A loop is entered to input all the records in file SEQFILE until the 
ENDFILE condition is raised. —The ENDFILE condition causes control to 
pass to the ON ENDFILE(SEQFILE) statement, and the on-unit is proc- 
essed. The flag MORE RECORDS is set on in the on-unit. Then the 
END statement on statement 31 is carried out. In the next iteration of the 
loop, the WHILE option will fail, and the loop is exited. 


The input field START WEEK is checked for valid values. If the value is 
out of range then the SIGNAL ERROR statement will raise the ERROR 
condition and the ON ERROR statement at is processed. The flag 
ERR_KEY 1s set before the signal is issued to indicate that the error has 
been raised by a SIGNAL statement. 


This ON ERROR statement establishes the action taken when an error is 
raised during processing of procedure RANDOM. After the on-unit is proc- 
essed, control is transferred to the END_PROC1 label to end the DIST pro- 
cedure. This error action is only active for the RANDOM procedure. When 
control returns to the DIST procedure, the ERROR on-unit established for 
DIST is reinstated. 


The ON KEY(INFILE) statement establishes the action to be taken when a 
KEY condition is raised in the RANDOM procedure. The ON KEY condi- 
tion is only active for the RANDOM procedure. Control is transferred from 
this on-unit to the statement immediately following the statement that raised 
the KEY condition. 


The ONCODB is used to determine the KEY condition raised. If the KEY 
error is “key not found,” then an error message is issued. 


If the raised condition is any KEY condition other than 51, a general key 
error message is produced. 


Control is transferred here when a valid record is read from file SEQFILE. 
The file INFILE will be read and processed according to the input fields 
START WEEK and NUMB_WEEKS. 


Call an external subroutine to do further processing. 
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C Chapter 11. Input and Output Statements 


This chapter is divided into three sections. The first discusses general input and 

output statements. The next two sections describe record data transmission, and 
stream data transmission, by describing the different ways that input and output 

statements can be used to move different forms of data. 


Input and Output 


Data is transmitted between storage locations, between external storage mediums, 
between work stations, and between applications by means of input and output 
statements. A collection of data external to a program is called a file. Transmission 
of data from a file to a program is called input. Transmission of data from a 

Cc program to a file is called output. (‘‘File” can also mean your work station, another 
program, or a communication line.) 


Input and output statements allow a source program to deal with the logical organ- 
ization of data in a file, rather than with its physical characteristics. To do this, PL/I 
uses models of AS/400 files. You can write a program without specific knowledge 
of the input/output devices that will be used when the program runs. A PL/I file can 
also be connected to different AS/400 files at various times during the running of a 
program. 


= There are input and output statements for two types of data transmission: record 
and stream. 


In record data transmission, the file is considered a collection of discrete records. 

On input, the data is transmitted exactly as it is specified in the record format of the 

AS/400 file. On output, the data is transmitted exactly as it is specified in the record 

format specified in the program. 

Record data transmission can be used for processing files that are written in any 
S representation, such as binary, decimal, or character. 

In stream data transmission, the organization of the data into records is ignored, and 

the data 1s treated as though it were a continuous stream of individual data values in 

character form. On input, if necessary, the data is converted from character form in 

the file to conform with the attributes of the data list item in the program. On 


output, the data is converted from the attributes of the data list item in the program 
to character form in the file. 


Record data transmission is more versatile than stream data transmission because 
record transmitted data can be processed in more ways, and record data trans- 
missions can be made to and from more types of AS/400 files. Any type of data 
can be transmitted using record data transmission because no conversion occurs. 
However, you must be aware of the structure of the data. 


‘ Stream data transmission 1s more versatile in its formatting of data, but requires 
more run time. 
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Files 


AS/400 Files 


The data transmission statements include the following input and output statements: 


° GET 

PUT 
READ 
WRITE 
REWRITE 
DELETE. 


The OPEN and CLOSE statements are not used for data transmission. 


This chapter discusses those aspects of input and output that are common to record 
and stream data transmission, including files and their attributes, and the relation- 
ship of files to AS/400 files. For further information on AS/400 files, see 

Chapter 6, “AS/400 PL/I File and Record Management” and Chapter 8, “Using 
AS/400 Files.” 


A file, as described in an AS/400 PL/I source program, is a model of an AS/400 file. 
It has significance only within the source program, and does not exist as a physical 
entity external to the program. However, the program description of the file deter- 
mines how input and output statements access and process the associated AS/400 
files. 


You can code the file record descriptions and other file information about the 
AS/400 file directly into your program (program-described), or you can allow the 
system to include this file information in your source program (externally described). 
For a description of how to include file information from externally described files 
into your source program, refer to “Using the % INCLUDE Directive for External 
File Descriptions” on page 8-73. 


The following AS/400 file types are supported by AS/400 PL/I: 


Display file 

Physical data base file 

Logical data base file 

Printer file 

Tape file 

Diskette file 

Inline file 

Data file management (DDM) file. 


The following AS/400 file types are supported by the System/38 Environment only: 


« Communications file 
e BSC file. 
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Use of the File Attributes 


File Name 


You specify information about a file ina DECLARE statement. A description of 
the syntax rules of this statement is given in “The DECLARE Statement” on 
page 12-1. The following sections describe the attributes which are common to 
both record and stream files. These attributes deal with naming files, and with the 
types and directions of data transmission used with files. 


A name that represents a file is a file constant. Each file must be associated with a 
file constant. To declare a file constant ina DECLARE statement, you specify the 
FILE attribute. Ifthe file constant is used as the name of an AS/400 file, it must 
not be more than ten characters long. 


Type Of Data Transmission 


You use the RECORD and STREAM attributes in the DECLARE statement to 
specify the type of data transmission used for the file. 


RECORD indicates that the file consists of discrete records, each of which consists 
of one or more data items in any form. Each record is transmitted as an entity to or 
from a variable. STREAM indicates that the data of the file is considered a contin- 
uous stream of data items in character form, assigned from the stream to variables 
or from expressions into the stream. 


The statements with which a file with the RECORD attribute can be used are the 
input/output statements OPEN, CLOSE, READ, WRITE, REWRITE, and 
DELETE, and the ON and SIGNAL statements. 


The statements with which a file with the STREAM attribute can be used are the 
input/output statements OPEN, CLOSE, GET, and PUT, and the ON and 
SIGNAL statements. 


Direction of Data Transmission 


You use the INPUT, OUTPUT, and UPDATE attributes to determine the direc- 
tion of data transmission permitted for a file. 


INPUT specifies that data is transmitted from a file to the program. It is valid with 
any file type except a printer file. 


OUTPUT specifies that data is transmitted from the program to create a new file or 
to extend an existing file. It is valid with any file type except an inline file. 
OUTPUT and STREAM are not valid with diskette files. 


UPDATE can only be used with RECORD. It specifies that the data can be trans- 
mitted in either direction. It also allows the insertion of records into an existing file 
and the altering of other records already in that file. UPDATE is valid only with 
physical and logical data base files, display, communications, and Bsc files. 
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Opening and Closing Files 


OPEN Statement 


Before a file can be used for input or output, it must be opened. Opening a file 
involves associating it with an AS/400 file. (If the attempted association is unsuc- 
cessful, the UNDEFINEDFILE condition is raised.) When processing 1s com- 
pleted, you may close the file. Closing a file involves disassociating the AS/400 file. 


PL/I provides two statements, OPEN and CLOSE, to do these functions. Use of 
these statements, however, is optional. 


When a file is opened for SEQUENTIAL INPUT or SEQUENTIAL UPDATE, 
the current position is the position at the start of the file. 


The OPEN statement associates a PL/I file with an AS/400 file. For more informa- 
tion on opening files, see “Opening and Closing Files” on page 7-11. The options 

of the OPEN statement are first evaluated, and the specification of attributes for the 
file is completed, as necessary. If the association can be made, the file is then asso- 

ciated with the AS/400 file. 


>>—OPEN-——FILE(file_constant) 


i ee | RS ies 
LINESIZE (expression) PAGES IZE (expression) 


FILE(file_constant) 
Specifies the name of the PL/I file that 1s opened. If the file is already open, the 
evaluated options are not used, and the file is unaffected. 


INPUT, OUTPUT, UPDATE 
Specifies attributes that augment the attributes specified in the file declaration, 
with which they must not conflict. 


TITLE(expression) 
The expression must be a character expression. 


The expression specifies the name of the AS/400 file that is opened. It can be a 
maximum of 33 characters in length. If you code less than 33 characters, it is 
padded on the right with blanks. If you code more than 33 characters, it is 
truncated on the right. 


You can use upper and lowercase characters, but the expression is converted to 
uppercase by the compiler. 


An EXTENDED name is delimited by quotes(”), which are considered part of 
the name. The characters can be any of the standard character set except a 
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blank, an asterisk, a single quote or double quotes. The characters within the 
quotes will not be monocased. 


AS/400 PLjI will only support the EXTENDED name in literals, therefore the 
only place where they can be used is in the TITLE option of the OPEN state- 
ment. 


Note: AAA is three characters and ”aaa” 1s five characters. This means that 
delimited names can be a maximum of eight characters. 


scciais biackeiia aael 
expression 


where ‘expression’ is: 


 Lewaeel leeeel — 
library_name/ (inember_name) 


title_variable 
Can be any valid program variable whose value is a valid AS/400 
expression. For example: 
ACCOUNTS RECEIVABLE 
= 'ACCTLIB/ACCOUNTS(ACCOUNT1) '; 
OPEN FILE (ACCTS) UPDATE 
TITLE (ACCOUNTS RECEIVABLE) ; 


expression 
Must consist of valid AS/400 file, library and member names. 


If library-name is omitted, *LIBL is assumed. 
If member-name is omitted, the first member in the file is used. 


In the following example: 


OPEN FILE (ACCTS) UPDATE 
TITLE ('ACCTLIB/ACCOUNTS (ACCOUNT1) '); 


ACCOUNTS 1s the AS/400 file name, ACCTLIB is the AS/400 library 
name, and ACCOUNT 1s the AS/400 member name. 


If you do not specify the library name, your statement would look like this: 


OPEN FILE (ACCTS) UPDATE 
TITLE ("ACCOUNTS (ACCOUNT1) ') ; 


LINESIZE(expression) 
An integer expression that specifies the length, in characters, of a line during 
subsequent operations on the file. New lines can be started by means of the 
control format items or by means of options in a PUT statement. If any 
attempt is made to position a file past the end of a line, a new line is started, 
and the file is positioned to the start of this new line. 


The implementation-defined values are 


Maximum line size 32 765 
Minimum line size 1 
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The default line size is the record length specified in the AS/400 file. 


The LINESIZE option can be specified only for a file that has the STREAM 
and OUTPUT attributes. 


PAGESIZ E(expression) 
The expression must be an integer expression. It specifies the number of lines 
on each page. The first attempt to exceed this limit raises the ENDPAGE con- 
dition. 


The implementation-defined values are: 


Maximum page size 32 76/7 
Minimum page size 1 
Default page size 60 


The PAGESIZE option can be specified only for a file that has the STREAM, 
OUTPUT, and PRINT attributes. 


Attribute Merging 


To open a file, PL/I uses information about the file from the following sources: 
¢ The attributes specified in a DECLARE statement. 


¢ The attributes specified in the OPEN statement (INPUT, OUTPUT, or 
UPDATE). 


¢ The options of the ENVIRONMENT attribute. 
When a file is opened, the system gets a complete specification of the file by the 
following procedure: 

1. The information from the above sources is collected. 


2. The implied attributes are added. (A list of implied attributes is given in 
“Implied Attributes” on page 12-5.) 


3. The default attributes are applied. 


If there is any conflict between attributes from any source after the application of 
default attributes, the UNDEFINEDFILE condition is raised. 


Implicit Opening 


A file is implicitly opened when one of the data transmission statements listed below 
is processed for a file for which an OPEN statement has not already been processed. 


Statement Implied Attributes 


GET STREAM INPUT 
PUT STREAM OUTPUT 
READ RECORD INPUT 
WRITE RECORD OUTPUT 
REWRITE RECORD UPDATE 
DELETE RECORD UPDATE 
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An implicit opening caused by one of the above statements is equivalent to pre- 
ceding the statement with an OPEN statement that specifies the implied attributes. 


Examples of File Opening 


The following example illustrates attribute merging for an explicit opening: 


DECLARE LISTING FILE PRINT; 
OPEN FILE(LISTING); 


Because there are no attributes on the OPEN statement, the attribute after merging 
is PRINT. After applying the implicit attributes, the attributes are STREAM, 
OUTPUT, and PRINT. After applying the default attributes, the completed attn- 
bute set is STREAM, OUTPUT, PRINT, and EXTERNAL. 


The following example illustrates implicit opening: 


DECLARE MASTER FILE KEYED INTERNAL; 
READ FILE (MASTER) INTO 
(MASTER RECORD) KEYTO(MASTERKEY) ; 


The attributes after merging (due to the implicit opening caused by processing the 
READ statement) are KEYED, RECORD, INPUT, and INTERNAL. (No addi- 
tional attributes are implied.) 


The completed attribute set after default application is KEYED, RECORD, 
INPUT, SEQUENTIAL, ENVIRONMENT(CONSECUTIVE), and INTERNAL. 


The following are examples of declarations of file constants, including the ENVI- 
RONMENT attribute: 


DECLARE FILE#3 FILE INPUT DIRECT 
ENVIRONMENT (BUFSIZE(80) 
CONSECUTIVE) ; 

OPEN FILE(FILE#3) ; 


This declaration specifies three file attributes: INPUT, DIRECT, and ENVIRON- 
MENT. DIRECT implies RECORD and KEYED. The scope is external, by 
default. The ENVIRONMENT attribute specifies that the file is of consecutive 
organization and contains records 80 bytes long. The KEY option must be speci- 
fied in each READ statement that refers to this file. 


DECLARE INVNTRY FILE UPDATE 
ENVIRONMENT (KEYDISP(10) KEYLENGTH(5) 
INDEXED) ; 

OPEN FILE(INVNTRY) ; 


This declaration specifies two file attributes: UPDATE and ENVIRONMENT. 

The implied attribute is RECORD. SEQUENTIAL and EXTERNAL are the 
default attributes. INVNTRY is a KEYED file with a KEYDISP of 10 and a 
KEYLENGTH of 5. Although the file actually contains a key within each record, 
the KEYTO option cannot be specified in a READ statement, because the KEYED 
attribute was not specified in the DECLARE statement. 
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In the above declaration, all necessary attributes are either stated or implied in the > 
DECLARE statement. None of the attnbutes can be changed in an OPEN state- 
ment. This declaration might have been written as follows: 


DECLARE INVNTRY FILE 


ENVIRONMENT (KEYDISP(10) KEYLENGTH(5) 
INDEXED) ; 


With such a declaration, INVNTRY can be opened for input, output, or update. It 
could, for example, be opened by means of any of the following statements: 

OPEN FILE (INVNTRY) INPUT; 

OPEN FILE (INVNTRY) OUTPUT; 

OPEN FILE (INVNTRY) UPDATE; 

OPEN FILE (INVNTRY); /*INPUT BY DEFAULT*/ 


By means of this technique, a file can be opened first as an input file and then 
closed and later opened as an output file. ) 


CLOSE Statement 
The CLOSE statement disassociates the specified file from the AS/400 file with 
which it was associated by the explicit or implicit file opening. 


>>—CLOSE—FILE(file_constant) ;——»<« 


FILE(file_constant) ) 
Specifies the name of the PL/I file that 1s to be disassociated from an AS/400 file. 


The CLOSE statement also disassociates from the file all attributes established for it 
by the implicit or explicit opening process. Although new attributes can be specified 
for the file constant in a subsequent OPEN statement, all attributes specified for it 
ina DECLARE statement remain in effect. 


Closing a file that is not open has no effect apart from increasing the run time of the 


program. 


A closed file can be opened again either explicitly or implicitly. 


If a file is not closed by a CLOSE statement, it is closed at the completion of the 
run unit. For a complete description of file opening and closing, see “Opening and 
Closing Files” on page 7-11. 


Record Data Transmission 


This section describes the file description attributes and input and output statements 

used in record data transmission. The ENVIRONMENT attribute and details of 

record data transmission input/output statements for each type of file are described 

in “The ENVIRONMENT Attribute” on page 7-1. The %INCLUDE directive 

and details of record data transmission input/output statements for externally 

described files are described in “Using the % INCLUDE Directive for External File J 
Descriptions” on page 8-73. 
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In record data transmission, data in a file is considered a collection of records. The 
READ statement either transmits a single record to a program variable, or sets a 
pointer to the record in a buffer. The WRITE or REWRITE statement transmits a 
single record from a program variable to the file. The DELETE statement removes 
a single record from a file. 


Although data can be transmitted to and from a file in blocks, the statements used 
in record data transmission are concerned only with records. The records are 
blocked and deblocked automatically. For more information on blocking and 
deblocking, refer to the description of the BLOCK option of the ENVIRONMENT 
attribute in “Blocking Option” on page 7-7. 


Use of File Description Attributes 


You use the file description attribute RECORD to indicate record data trans- 
mission. You can also use the file description attributes INPUT, OUTPUT, 
UPDATE, SEQUENTIAL, DIRECT, KEYED, and ENVIRONMENT to give 
the system additional information about the file. The syntax rules for all of these 
attributes are given in “File Attributes” on page 12-6. 


AS/400 File Organization 


You specify file organization by means of the ENVIRONMENT options CON- 
SECUTIVE, INDEXED, and INTERACTIVE. The organization of a file deter- 
mines how data is recorded in a file and how the data is subsequently retrieved for 
transmission to the program. 


File organization for each of the types of AS/400 files is discussed in “File Organiza- 
tion Options” on page 7-2. 


Other characteristics of AS/400 files can also be specified in the ENVIRONMENT 
attribute. This attribute is discussed in “The ENVIRONMENT Attribute” on 
page 7-1. 


File Access 


The types of file access are: 


© SEQUENTIAL 
¢ SEQUENTIAL KEYED 
e DIRECT. 


You use the SEQUENTIAL, KEYED, and DIRECT attributes to specify these. 
(The DIRECT attribute implies the KEYED attribute, so when the file access is 
given as DIRECT, KEYED is understood.) Syntax of these attributes is described 
in “File Attributes” on page 12-6. They describe how AS/400 files are accessed. 


You specify the KEYED attribute when you use one of the key options (KEY, 
KEYFROM, and KEYTO) of the data transmission statements. For data base files 
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with arrival sequence access, or for subfiles, the key in the KEY, KEYFROM, or 
KEYTO options is a relative record number. 


With SEQUENTIAL access, the key options are not valid; with SEQUENTIAL 
KEYED access, they are optional; with DIRECT access, KEY or KEYFROM is 
required. 


With physical or logical data base files, SEQUENTIAL specifies that records with 
CONSECUTIVE file organization are accessed using the arrival sequence access 
path, and that records with INDEXED file organization are accessed using the 
keyed sequence access path. A file with SEQUENTIAL KEYED access can also be 
used for direct access or for a mixture of direct and sequential access. Existing 
records of a file in a sequential update file can be modified or deleted. 


Any type of file may have SEQUENTIAL access. Physical and logical data base 
files, or display files in which subfile processing is used with specific relative record 
numbers, may have SEQUENTIAL KEYED access. Only physical and logical data 
base files may have DIRECT access. 


Direction of Data Transmission 


The attributes INPUT, OUTPUT, and UPDATE are all valid with record data 
transmission. 


INPUT allows the use of the READ statement only. OUTPUT allows the use of 
the WRITE statement only. UPDATE allows the use of the READ statement with 
any organization or access, and of the WRITE statement with INTERACTIVE 
organization or DIRECT access. For the use of the REWRITE and DELETE 
statements, see “REWRITE Statement” on page 11-15 and “DELETE Statement” 
on page 11-16. UPDATE is valid only with physical and logical data base files, 
display, communications, and Bsc files. 


Variables can be transmitted by record data transmission statements. Although 
program control data can be transmitted, it may no longer be valid after it is read. 


Data Transmission Statements 
The statements that transmit records to or from files are READ, WRITE, and 
REWRITE. The DELETE statement deletes a record from an update file. The 
attributes of the file determine which statements can be used. 


When an input or output statement is processed, the file options are evaluated. If 
the file is not already open, it is opened implicitly. The validity of the statement is 
checked against the complete set of attributes. If the statement is valid, then the 
input or output is processed. 


The following sections describe the data transmission statements used for record 


input/output. The statements are discussed first, followed by the statement options 
and a discussion of the statements and file attributes that apply to each option. 
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The file organization and file access that you specify in the DECLARE statement 
sometimes impose restrictions on the data transmission statements. These 
restrictions are described in the appropriate sections below. 


Each data transmission statement contains an OPTIONS option which allows you 
to access AS/400 system functions. For a discussion of this option and its parame- 
ters, see “The OPTIONS Option of Record Data Transmission Statements” on 
page 7-13. 


READ Statement 


The READ statement can be used with any RECORD INPUT or UPDATE file. 
It transmits a record from the file to the program by means of one of the following 
options: 


¢ INTO, which transfers the record to a variable (move mode). 
¢ SET, which sets a pointer to the record in the buffer (locate mode). 


READ a record from a file 


eee ee 


(SET pointer_variable) 


KEY(expression) 


KEYTO(character_variable) 


FILE(file_constant) 
Specifies the name of the PL/I file to which data is to be transmitted. The PL/I 
file name is associated with an AS/400 file name through the TITLE option of 
the OPEN statement. 


INTO (variable) 
Specifies a variable into which the record is read. Variable is a connected aggre- 
gate or scalar variable. 


SET (pointer_variable) 
Specifies a pointer-variable that is set to point to the location in the buffer that 
contains the record number. Pointer_variable is a simple non-based variable 
with the pointer attribute. 


KEY (expression) 
Identifies a particular record. KEY can be CHARACTER VARYING. KEY 
is not valid with SEQUENTIAL access. 


KEYTO (character_variable) 
Specifies the variable to which the key of a record will be assigned. KEYTO 
may be used instead of KEY with SEQUENTIAL KEYED. KEYTO can be 
CHARACTER VARYING. 
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Options 
Are different for the three different types of READ statements. The Options for 
each type of READ statement are described below. 


Read from a CONSECUTIVE File 


>>—OPTIONS (—RECORD(character_expression)—POSITION( NEXT 


PREVIOUS 
FIRST 
LAST 


>—— INDICATORS (variable)—)—;——»« 


Abbreviations: NXT for NEXT 
PRV for PREVIOUS 


See ‘“The OPTIONS Option of Record Data Transmission Statements” on 
page 7-13 for a description of the syntax of the Options option. Note also that: 


¢ KEY must be a structure reference or scalar expression. 
¢ RECORD, KEY and KEYTO can be CHARACTER VARYING. 


¢ KEY is not valid with SEQUENTIAL access, optional with SEQUENTIAL 
KEYED access, and required with DIRECT access. KEYTO may be used 
instead of KEY with SEQUENTIAL KEYED. 


¢ KEY is mutually exclusive with POSITION. 
¢ POSITION is not valid with DIRECT access. 
¢ INDICATORS is valid only with SEQUENTIAL or SEQUENTIAL KEYED 


access. 


¢ If POSITION is not specified, the default is POSITION(NEXT). 
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Read from an INDEXED File 


>>— OPTIONS (—RECORD(character_express ion) —KEYSEARCH( EQUAL 
AFTER 
BEFORE 
EQLAFT 


EQLBFR 


>——POSITION( NEXT———) —NBRKEYFLDS (integer_constant)—)—;—_»> 


PREVIOUS—— 
NXTUNQ——+ 


t+ PRVUNQ— 


r—NXTEQL 


t———PRVEQL 
[ee 
LAST 


Abbreviations: NXT for NEXT 
PRV for PREVIOUS 


See “The OPTIONS Option of Record Data Transmission Statements” on 
page 7-13 for a description of the syntax of the Options option. Note also that: 


¢ KEY must be a structure reference or scalar expression. 
¢ RECORD, KEY and KEYTO can be CHARACTER VARYING. 
¢ KEY is mutually exclusive with POSITION. 


¢ KEY is not valid with SEQUENTIAL access, optional with SEQUENTIAL 
KEYED access, and required with DIRECT access. KEYTO may be used 
instead of KEY with SEQUENTIAL KEYED. 


¢ KEYSEARCH 1s not valid with SEQUENTIAL access. 

¢ KEYSEARCH is not allowed if KEY is not specified. 

e POSITION is not valid with DIRECT access. 

¢ If POSITION is not specified, the default is POSITION(NEXT). 


¢ NBRKEYFLDS is not allowed if POSITION(NEXT | PREVIOUS | FIRST | 
LAST) is specified. 
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Read from an INTERACTIVE File 


>>—OPTIONS——(—RECORD(character_expression)—> 


>— INDICATORS (variable)—MODIFIED—)—;——»>« 


See “The OPTIONS Option of Record Data Transmission Statements” on 
page 7-13 for a description of the syntax of the Options option. Note also that: 


KEY must be a structure reference or scalar expression. 
RECORD, KEY and KEYTO can be CHARACTER VARYING. 
KEY is mutually exclusive with MODIFIED. 


KEY is not valid with SEQUENTIAL access and optional with SEQUEN- 
TIAL KEYED access. KEYTO may be used instead of KEY with SEQUEN- 
TIAL KEYED. 


INDICATORS must be CHARACTER without the VARYING attribute. 
MODIFIED 1s not valid with SEQUENTIAL access. 


WRITE Statement 


The WRITE statement can be used with any OUTPUT or INTERACTIVE 
UPDATE or DIRECT UPDATE file. It transmits a record from the program and 
adds it to the file. 


>>—WRITE—FILE(file_constant)—FROM(variable)——> 


_— expression x 
i RENIN IEnRIINES (a 
OPTIONS (RECORD(character_expression)—INDICATORS (variable) ) 


p east | 


Additional Syntax: 


FROM must be a connected aggregate or scalar variable. 
KEYFROM must be a scalar expression. 
KEYFROM and RECORD can be CHARACTER VARYING. 


KEYFROM is not valid with SEQUENTIAL access, optional with 
SEQUENTIA KEYED access and required with DIRECT access. 


Note: KEYFROM is required with INTERACTIVE organization and 
SEQUENTIAL KEYED access. 
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¢ INDICATORS, when used with CONSECUTIVE organization, is optional 
with SEQUENTIAL access and not valid with SEQUENTIAL KEYED or 
DIRECT access. 


¢ INDICATORS is not valid with INDEXED organization. 
¢ INDICATORS must be CHARACTER without the VARYING attribute. 


For printer files that contain more than one record format, you must specify the 
RECORD option. Similarly, you must specify the RECORD option for a WRITE 
to a multiple format logical file. The only exception is when a format selection 
program is defined. For information on format selection programs, see the 
description of the FMTSLR parameter on the CL command CRTLF in the 
Programming: Control Language Reference. 


For logical data base files, it is possible to map one record format to multiple base 
physical file members with the DIAMBRS parameter on the CL commands 
CRTLF and ADDLFM. 


REWRITE Statement 


The REWRITE statement replaces a record in an update file. It is only allowed for 
physical and logical data base files and display files. It cannot be used for a display 
file with INTERACTIVE organization and SEQUENTIAL access. 


ae iii (RE, 
KEY (expression) 


We cto ennai 
OPTIONS (RECORD(character_expression)—INDICATORS (variable) ) 


Additional Syntax: 


e FROM must be a connected aggregate or scalar variable. 
¢ KEY must be a structure reference or scalar expression. 
¢ KEY and RECORD can be CHARACTER VARYING. 


¢ KEY ts not valid with SEQUENTIAL access, optional with SEQUENTIAL 
KEYED access, and required with DIRECT access. 


¢ INDICATORS must be CHARACTER without the VARYING attribute. 
¢ INDICATORS is not valid with CONSECUTIVE organization. 


For non-keyed sequential update files, the REWRITE statement must be preceded 
by a READ statement, with no intervening input or output statements for the same 
file. It specifies that the last record read from the file is rewritten. Consequently, a 
record must be read before it can be rewritten. For direct update files and keyed 
sequential update files, any record can be rewritten regardless of whether it has first 
been read. 
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The first statement that accesses the file cannot be a REWRITE statement without 
the KEY option. No subsequent REWRITE or DELETE statement without a 
KEY is allowed until another READ statement is processed. 


If duplicate keys exist and the key expression locates a duplicate key, the first dupli- 
cate in the access path identifies the record rewritten. 


DELETE Statement 


The DELETE statement deletes a record from an update file. It is only allowed for 
physical and logical data base files. 


a 
KEY (expression) 
a (pean aeneaanee na 
OPTIONS (RECORD({(character_expression) ) 


Additional Syntax: 


¢ KEY must be a structure reference or scalar expression. 
¢ KEY and RECORD can be CHARACTER VARYING. 


¢ KEY is not valid with SEQUENTIAL access, optional with SEQUENTIAL 
KEYED access, and required with DIRECT access. 


If you omit the KEY option for a sequential update file, the record deleted is the 
last record read. No subsequent DELETE or REWRITE statement without a 
KEY is allowed until another READ statement is processed. 


If duplicate keys exist and the key expression locates a duplicate key, the first dupli- 
cate in the access path identifies the record deleted. 


If the first statement that accesses the file is a DELETE statement, it must specify 
the KEY option. 


Options of Record Data Transmission Statements 
This section describes the options of record data transmission statements. The 
options can appear in any order in the statements. Figure 11-1 shows valid combi- 
nations of statement options and file organizations. For the complete rules on using 
these statements, refer to Appendix C, ‘Valid Combinations of Options for 
Input/Output Statements” on page C-1. 
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READ 

FILE 

INTO|SET 

KEY 

KEYTO 

OPTIONS 
RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


WRITE 
FILE 


FROM 

KEYFROM 

OPTIONS 
RECORD 
INDICATORS 


OOONRD 


REWRITE 
FILE 
FROM 
KEY 
OPTIONS 
RECORD 
INDICATORS 


DELETE 
FILE 
KEY 
OPTIONS 
RECORD 


_ 
Ba 
— 


pepe 


Figure 11-1. Valid Combinations of Record Statement Options 


Key: 
R Required 
O Optional 
— Error or ignored 


Notes: 

(1) DIRECT access is invalid with INTERACTIVE 
organization. 

(2) Invalid with SEQUENTIAL access, optional with 
SEQUENTIAL KEYED access, and required with DIRECT 
access. 

(3) KEYTO may be used instead of KEY with SEQUENTIAL 
KEYED access. 
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(4) Invalid with SEQUENTIAL access. 
(5) Invalid with DIRECT access. 
(6) Optional with SEQUENTIAL access. 


The options are discussed in the following order: 


FILE 

INTO 
FROM 

SET 

KEY 
KEYFROM 
KEYTO 
OPTIONS 


FILE (file_constant) Option 


The FILE option must appear in every record data transmission statement. It spec- 
ifies the file to or from which data 1s transmitted. 


If the file specified is not open, it 1s opened implicitly. 


INTO (variable) Option 


The INTO option of the READ statement specifies a variable into which the record 
is read. Either the INTO or the SET option must be used with every READ state- 
ment. 


The INTO variable can be a VARYING length string. 
If the INTO variable is a structure element, it must be connected. 


If the INTO variable is shorter than the record length, the record is truncated on the 
right, and the RECORD condition is raised. 


If the INTO variable is equal to the record length, the record is copied to the vari- 
able, and no condition is raised. If the INTO variable is CHARACTER 
VARYING, the string length is set so that it can be referenced by the LENGTH 
function. 


If the INTO variable is larger than the record length, the record is copied to the 
variable. If the INTO variable is fixed-length, the RECORD condition is raised. 


If the INTO variable is CHARACTER VARYING, the string length is set so that 
it can be referenced by the LENGTH function; no condition is raised. If the 
CHARACTER VARYING record read in is shorter than the INTO variable, the 
bytes of the INTO variable not used for the record retain their previous contents; 
they are not filled with blanks. If the CHARACTER VARYING record read in is 
longer than the INTO variable, the record is truncated on the right, and the 
RECORD condition is raised. The byte count at the beginning of the record is 
changed so that it holds the number of bytes actually read in. 
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The following example specifies that the next sequential record is read into the vari- 
able RECORD: 


READ FILE (DETAIL) INTO (RECORD1); 


FROM (variable) Option 


The FROM option must be used in WRITE and REWRITE statements. It speci- 
fies the variable from which the record is written. 


If the FROM variable is a structure element, it must be connected. 


If the FROM variable is shorter than the record length, it is padded on the right 
with blanks. If the FROM variable is longer than the record length, it is truncated 
on the right. 


In the following example, the WRITE and REWRITE statements specify that the 
value of the variable DETAILRECORD is written into the file MASTER. The 
WRITE statement specifies a record added to aSEQUENTIAL OUTPUT file. 


WRITE FILE(MASTER) FROM(DETAILRECORD) ; 


The REWRITE statement specifies that DETAILRECORD is to replace the last 
record read from a sequential update file. 


READ FILE(MASTER) INTO(DETAILRECORD) ; 
/* PROCESSING. NO I/O TO FILE MASTER */ 
REWRITE FILE(MASTER) FROM(DETAILRECORD) ; 


SET (pointer_variable) Option 


The SET option of the READ statement specifies a pointer variable that is set to 
point to the location in the buffer that contains the required record. Either the 
INTO or the SET option must be used with every READ statement. 


You can use the SET option to avoid raising the RECORD condition. You can 
also use the SET option to improve program performance: the program will run 
faster if it does not move the record from the buffer to your own data area. 


A READ statement transfers a block of data from the data set to a buffer, if neces- 
sary, and then sets a pointer variable named in the SET option to point to the 
location in the buffer of the next record. The data in the record can then be proc- 
essed by means of a reference to the based variable associated with the pointer vari- 
able. 


Alignment errors can occur if the mapping of the based variable does not exactly 
match the mapping of the input record in the buffer. For example, if the input 
record contains an unaligned BINARY FIXED (31) field, the based variable must 
be declared with the UNALIGNED attribute. Otherwise, an error would occur, 
since the default for BINARY FIXED variables is ALIGNED. 


If you specify the SET option, the record condition will not be raised. 
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The record is available only until the processing of the next input/output operation 
or CLOSE statement that refers to the same file. 


The following example specifies that the value of the pointer variable P is set to the 
location of the next sequential record in the buffer: 


READ FILE(X) SET(P); 
The pointer is invalidated by the next operation on this file. 


If indicators are defined within the record buffer, the pointer is set to the start of the 
indicators, which are located at the start of the record buffer. 


KEY (expression) Option 


The KEY option of the READ, REWRITE, and DELETE statements identifies a 
particular record. 


The KEY option is required for DIRECT files, and optional for SEQUENTIAL 
KEYED files. 


The KEY expression can be a scalar expression or a structure reference. 


If a scalar expression is used in the KEY option, it is evaluated and, if necessary, 
converted to a binary fixed-point value with a precision of 31 for a CONSEC- 
UTIVE or INTERACTIVE file, or to a character value for an INDEXED file. 
This key determines which record will be processed. If the specified key is not valid, 
the KEY condition is raised. 


For an INDEXED file, the data type of the key should match the data type of the 
key field(s) defined for the record format. If you are using numeric data base keys, 
the key you reference must be an element of a structure. Otherwise, the key is con- 
verted to character format. 


The number of key fields included in the key is determined by the NBRKEYFLDS 
option (see “NBRKEYFLDS Parameter” on page 7-18). If NBRKEYFLDS is not 
specified, the length of the expression (or its current length, if it is CHARACTER 
VARYING) 1s passed to the system. Refer to the Programming: Control Language 
Reference for information on the generic key search that will be processed if the key 
length that is passed is between key field lengths. 


If there is a duplicate key, the key that is found depends on the KEYSEARCH 
value. If the value is BFR or EQLBFR, the last duplicate key value is located. For 
all other values of KEYSEARCH, the first duplicate key value is located. 


The following example specifies that the record identified by the value 1n the vari- 
able STKEY is read into the variable [TEM: 


READ FILE(STOCK) INTO(ITEM) KEY(STKEY); 
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KEYFROM (expression | *) Option 


The KEYFROM option of the WRITE statement specifies a key that identifies the 
location in the file to which the record is transmitted by the WRITE statement. 


KEYFROM 1s required for files with DIRECT access and optional for files with 
SEQUENTIAL KEYED access. (An exception: KEYFROM is required with 
INTERACTIVE SEQUENTIAL KEYED.) 


KEYFROM(expression) 
The expression in the KEYFROM option is evaluated and, if necessary, con- 
verted to a binary fixed-point value with a precision of 31 for CONSECUTIVE 
or INTERACTIVE organization or to a character value for INDEXED organ- 
ization. This value is used as the key of the record when it is subsequently 
written. If the specified key is not valid, the KEY condition is raised. 


KEYFROM(expression) may only be used for INDEXED files if the ENVI- 
RONMENT options KEYDISP and KEYLENGTH are specified. 


KEYFROM(*) 
When KEYFROM(\*) is specified, the * indicates that the key is imbedded in 
the associated record, that a keyed operation is being processed and that the key 
is not moved into the record by PL/I. Since the AS/400 data base supports non- 
contiguous keys (which may be of any data type), KEYDISP and 
KEYLENGTH are not applicable because they imply that the key is contig- 
uous. 


If you specify the ENVIRONMENT option DESCRIBED for an INDEXED 
file, you must specify KEYFROM(*). 


The KEYFROM(*) option is not allowed for CONSECUTIVE or INTERAC- 
TIVE files. 


Any KEYFROM value except * for an INDEXED file will be used to update the 
key field in the record. The embedded key is overwritten. 


The following example specifies that the stored value of LOANREC is written as a 
record in the file LOANS, and that the value of LOANNO is used as the key with 
which it can subsequently be retrieved: 


WRITE FILE(LOANS) FROM(LOANREC) KEYFROM(LOANNO) ; 


KEYTO (character_variable) Option 


The KEYTO option of the READ statement specifies the variable to which the key 
of a record will be assigned. 


KEYTO may be specified instead of the KEY option for a file with SEQUENTIAL 
KEYED access. 


If the KEYTO value is a character scalar, and the file is CONSECUTIVE or 
INTERACTIVE, the relative record number, which is returned by the system in 
fixed binary format, is converted to character format. If the KEYTO value is a 
character scalar and the file is INDEXED, no conversion is attempted. The key 
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data returned by the system is moved into the character variable as if the key were 
character. 


For physical or logical data base files for which CONSECUTIVE organization is 
specified, the relative record number is returned. For subfiles the relative record 
number within the subfile is returned. For physical or logical data base files for 
which INDEXED organization is specified, the key value of the record just read 1s 
returned. 


The following example specifies that the next record in the file DETAIL is read into 
the variable INVTRY and that the key of the record is made available in the vari- 
able KEYFLD: 


READ FILE(DETAIL) INTO(INVTRY) KEYTO(KEYFLD) ; 


OPTIONS Option 


The OPTIONS option of the READ, WRITE, REWRITE, and DELETE state- 
ments is implementation-defined, and is discussed in ‘The OPTIONS Option of 
Record Data Transmission Statements” on page 7-13. 


Stream Data Transmission 


There are three types of stream data transmission: stream data transmission, keyed 
data transmission, and record data transmission. Stream data transmission is the 
slowest form of transmission, and keyed data transmission is the fastest. 


This section describes the input and output statements used in stream data trans- 
mission. Those features that apply to stream and record data transmission, 
including files, file attributes, and opening and closing files, are described in 
Chapter 11, “Input and Output Statements.” 


Stream input/output is permitted with physical data base, logical data base, diskette 
(input only), tape, printer, and inline files. It is not permitted with display, BSc, or 
communications files. 


In stream data transmission, a file is treated as a continuous stream of data values in 
character form, without any delimiters between values. A file created or accessed by 
stream data transmission is, however, considered to consist of a series of lines of 
data and has a line size associated with it. A line is generally equivalent to a record 
in the file, though the line size and record size are not necessarily the same. Stream 
data transmission can move only problem data, not program control data. 


Only edit-directed stream data transmission is allowed. Edit-directed data trans- 
mission transmits the values of data items and requires that you specify the format 
of the values in the stream. The values are recorded externally as a string of charac- 
ters. 


On input, the value of each data item is converted, when necessary, to the attributes 


of the variable it is being assigned to. On output, the value of each data item 1s 
converted to the character representation specified by the associated format item and 
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placed in the stream in a field whose width may also be specified by the format 
item. 


File Description Attributes 
You use the file attribute STREAM to indicate stream data transmission. The file 
description attributes INPUT, OUTPUT, and PRINT can also be used. Informa- 
tion on the syntax of these attributes is in “File Attributes” on page 12-6. 


Direction of Data Transmission 


The INPUT and OUTPUT attributes are valid with stream data transmission. 
INPUT allows use of the GET statement. OUTPUT allows use of the PUT state- 
ment. 


Declaring Print Files 


You declare a print file by specifying the PRINT attribute. This indicates that you 
intend to print the file; that is, the data associated with the file will appear on 
printed pages, although it may first be written on some other device. 


The first data byte of each record of a print file is reserved for a carriage control 
character. When you specify PRINT, the system provides first character forms 
control (FCFC) support. For a description of FCFC, see the Programming: Data 
Management Guide. 


You can use the LINE option or PAGE option of the PUT statement only if you 
specify PRINT. 


Data Transmission Statements 
The same conversion restrictions apply for the GET and PUT statements as are 
described in “Assignment Statement” on page 13-1. 


The variables to which data items are assigned, and the expressions from which they 
are transmitted, are generally specified in the data list of a data_specification in each 
GET or PUT statement, which also contains a format list. Each data list item in 
the data list is associated with a data format list item in the format list. A format 
list item specifies the format of the data item on the external medium. The state- 
ments can also include options that specify the position of the data items in the 
stream relative to the preceding data items. 


Only stream files can be processed with the GET and PUT statements. 


The following sections describe the GET and PUT statements, first discussing each 
statement and then the statement options and the file attributes to which they apply. 
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GET Statement 


The GET statement is a stream input data transmission statement that assigns data 
from a file to one or more variables. 


>>—GET—> 


FILE(file_constant)——data_specification 


(expression) 


(expression) 
data_specification 


(expression) 


(expression) 


You can omit the data specification only if you include the SKIP option. 
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PUT Statement 


The PUT statement is a stream output data transmission statement that transmits 
data to a file. 


>>—PUT—FILE(file_constant)——data_specification 


LINE (expression) 


(expression) 


LINE (expression) 
LINE (expression) 
(expression) 
LINE (expression) 


data_specification 


LINE (expression) 


(expression) 


LINE (expression) 
LINE (expression) 


(expression) 


LINE(expression) 


You can omit the data specification only if you include one of the control options 
(PAGE, SKIP, or LINE). 
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Options of Stream Data Transmission Statements 
The options you can specify on stream data transmission statements are given in the 
following sections. 


FILE (file_constant) Option 


The FILE option specifies the file to or from which data is transmitted. It must be 
a stream file. 


file_constant 
The name of the file to or from which data is transmitted. 


If you omit the FILE option from a GET statement, the file SYSIN is the default. 
If you omit it from a PUT statement, the file SYSPRINT is the default. 


If you do not explicitly open the file, it is implicitly opened for stream data trans- 
mission when the first GET or PUT statement is processed for the file. 


SKIP (expression) Option 


The SKIP option specifies a new current line or record within the file. 


expression 
An integer expression that specifies the number of the line or record, relative to 
the current line or record, skipped to. The expression must be less than or 
equal to 32 767 for input and output files, greater than zero for input files and 
non-print output files, and greater than or equal to zero for print files. If you 
omit the expression, the default is 1. 


The SKIP option takes effect before the transmission of values defined by the data 

specification (if present). For example, the following statement writes the values of 
variables X, Y, and Z to the output file SYSPRINT starting on the third line after 

the current line: 


PUT EDIT(X,Y,Z) (F(3),A(2),F(4)) SKIP(3); 


The effect of the SKIP option is the same as for the SKIP format item (see “SKIP 
Format Item” on page 11-39). 


PAGE Option 


You can specify the PAGE option only for print files. It defines a new current page 
within the file. 


The page remains current until a PUT statement with the PAGE option is proc- 
essed, until a PAGE format item is encountered, or until the implicit action for the 
ENDPAGE condition is processed. A new page is then defined, the page number is 
increased by one, and the line count 1s set to 1. 


The PAGE option takes effect before the transmission of any values defined by the 


data specification (if present). If PAGE and LINE appear in the same PUT state- 
ment, the PAGE option is applied first. 
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LINE (expression) Option 


You can specify the LINE option only for print files. It defines a new current line 
for the file. 


expression 
An integer expression that specifies the number of the new current line on the 
current page. The expression must be less than or equal to 32 767. If the 
expression is less than or equal to zero, LINE(1) is assumed. 


The LINE option takes effect before the transmission of any values defined by the 
data specification (if present). If both the PAGE option and the LINE option 
appear in the same statement, the PAGE option is applied first. For example: 


PUT FILE(LIST) EDIT(P,Q,R) 
(F(3),A(2),F(4)) LINE(34) PAGE; 


prints the values of the variables P, Q, and R on a new page, starting at line 34. 


The effect of the LINE option is the same as for the LINE format item (see “LINE 
Format Item” on page 11-39). 


Data Specifications 


Data Lists 


Data specifications in GET and PUT statements identify the data to be transmitted 
and its format in the data stream. 


>>— EDI T—(data_list) (format_list)——>~< 


The syntax of a data list is shown below: 


—_ 


terative_specification 
where 'iterative_specification’ js: 


>———— (data_list—DO—reference = specification)——> 


data_list_item 
The data type of a data_list_item must be arithmetic or string. 
A data_list_item may be a scalar variable (on input and output), a scalar 
expression (on output), or an array or structure variable. If you specify an 


aggregate in a data list, each element of the array or field of the structure is 
treated as a separate data_list item, and is paired with a data format item. 
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iterative_specification 
The meaning of the specification and of the expressions in the specification are 
the same as those in a DO statement (described under “DO Statement” on 
page 13-5). 


Each iterative_specification must be enclosed in parentheses. If a data specifica- 
tion contains only an iterative_specification, two sets of outer parentheses are 
required, since the data list is enclosed in parentheses and the iterative_ specifi- 
cation must have a separate set. 


When iterative_specifications are nested, the nghtmost DO is at the outer level 
of nesting. For example: 


GET EDIT (((ARRAY1(I,J) 
DO I = 1 TO 2) 
DO J = 3 T0 4)) (F(3)); 


In this example, there are three sets of parentheses, as well as the set that 
delimits the subscripts. The outermost set encloses the data list; the next is 
required by the outer iterative_specification; the third is required by the inner 
iterative-specification. This statement is equivalent to the following nested 
do-groups: 
D0 J = 310 4; 

DO IT =1 10 2; 

GET EDIT (ARRAY1 (I,J)) (F(3)); 

END; 

END: 


Values are assigned to the elements of ARRAY 1 in the following order: 
ARRAY1(1,3), ARRAY1(2,3), ARRAY1(1,4), ARRAY1(2, 4) 


When the specification is completed, processing continues with the next 
data_list_item. 


The maximum level of nesting of iterative_specifications within a data list is 49. 


Format Lists 
Format lists in GET and PUT statements identify the format of the data on the 
external medium. 


[ 


format_ite 


iteration_factor—format_item 


iteration_factor—(format_list) 


iteration_factor 
An integer constant that specifies the number of times the associated format- 
item or format_list is repeated. A blank must separate the constant and the fol- 
lowing format_item. 
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The associated format_item or format-list is that item or list of items imme- 
diately to the right of the iteration-factor. 


format_item 
Specifies either a data format item or a control format item. The format items 
and their syntax are shown below. Format items are discussed in “Format 
Items” on page 11-31. 


Format Items and their Syntax 


Data Format Items 


character Al(field_width)}' 

bit B[1|4][(field_width)]' 
floating-point E(field_width| fractional_digits}) 
fixed-point F(field_width{,fractional_digits}) 


Control Format Items 


column-position COLUMN(chAaracter_position) 
line-position LINE(line_number) 

paging PAGE 

line skipping SKIP[(relative_line)| 

spacing X(field_width) 


Note: ‘field width must be specified in a GET statement but is optional in a PUT 
statement. 


The first data format item is associated with the first data list item, the second data 
format item with the second data list item, and so on. If there are fewer data format 
items than data list items, the format list is reused. If there are more format items 
than data list items, the excess format items are ignored. 


A data format item describes the external format of a single data item. 
A control] format item specifies the layout of data values within a file. 


If one or more control format items are encountered before a data format item, the 
corresponding control actions are processed first, and then the data list item is trans- 
mitted according to the data format item. 


In the input stream, all blanks and apostrophes are treated as characters. It is not 
necessary to enclose strings in apostrophes. Apostrophes should not be doubled, 
nor should the letter B be used to identify bit values. If characters in the stream 
cannot be interpreted in the manner specified, the conversion condition is raised. 


Example of an input specification: 


GET EDIT (NAME, DATA, SALARY) 
(A(10), X(2), A(6), F(6,2)); 
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This example specifies the following: 


The first ten characters in the stream are considered character data, and are 
assigned to NAME. 

Skip the next two characters. 

The next six characters are considered character data, and are assigned to 
DATA. 

The next six characters are considered an optionally signed decimal fixed-point 
constant and are assigned to SALARY. 


In the output stream, blanks are not automatically inserted to separate data values. 


String data is left-adjusted within the field width specified; arithmetic data is right- 
adjusted. Because of the rules for conversion of arithmetic data to character type, 
which can insert up to three leading blanks (in addition to any blanks that replace 
leading zeros), at least one blank will precede an arithmetic item in the converted 
field. However, leading blanks do not appear in the stream unless the specified field 
width allows for them. 


Example of an output specification: 


PUT EDIT('INVENTORY=" | | INUM, INVCODE) 
(A,F(5))5 


This example specifies that the character constant 'INVENTORY = ' is to be con- 
catenated with the character value of INUM and placed in the stream in a field 
whose width is the length of the resultant string. Then the value of INVCODE is 
to be converted to character to represent an optionally signed integer constant 


placed in the stream right-adjusted in a five-character field (leading characters may 
be blanks). 


Truncation, due to an inadequate field-width specification, is on the left for arith- 
metic items and on the right for string items. For example: 


DECLARE INUM CHARACTER(5), 
INVCODE FIXED DECIMAL (5); 


PUT EDIT ('INVENTORY="| | INUM, INVCODE) 
(A(13) ,F(5)) 


This example is similar to the preceding example, except that the length of the char- 
acter constant 'INVENTORY = ' and the length of INUM together exceed the 
length specified in the format list item A(13). When INUM is concatenated with 
'INVENTORY = |, its last two characters will be lost. 


The PAGE and LINE format items can be used only with print files and, conse- 
quently, can only appear in PUT statements. The SKIP, COLUMN, and X-format 
items can be used with both input and output files. 


The PAGE, LINE, and SKIP format items have the same effect as the corre- 
sponding options of the PUT statement (and of the GET statement, in the case of 
SKIP), except that the format items take effect when they are encountered in the 
format list, whereas the options take effect before any data is transmitted. 
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The transmission is complete when the last data list item has been processed using 
its corresponding format item. 


Format items are specified in a format list in the data specification of a GET or 
PUT statement. (See “GET Statement” on page 11-24, “PUT Statement” on 
page 11-25, and “Format Lists” on page 11-28.) 

The two types of format items are data format items, which describe the external 
representation of data items, and control format items, which specify the formatting 
of data items. 


Control format items take effect before values defined in the data specification are 
transmitted. 


The format items are described in the following sections in alphabetical order. 


A-Format Item 


The character format item describes the external representation of a string of charac- 
ters. You can use it for all problem data types. 


For input: 


p>——A(field_width)—»< 


For output: 


cede 


field_width 
An integer constant up to 32 767 that specifies the number of character posi- 
tions in the data stream that contain, or will contain, the character value. 


On input, the specified number of characters is obtained from the data stream and 
assigned to the data item with any necessary conversion, truncation, or padding. 
The field_width is always required on input; if it is zero, a null value is obtained. 
Apostrophes in the stream are treated as characters. 


On output, the data list item is converted, if necessary, to a character value and is 
truncated or extended with blanks on the right to the specified field_width before 
being placed into the data stream. If the field_width is zero, no characters are 
placed into the data stream. Enclosing apostrophes are not inserted and contained 
apostrophes are not doubled. If you do not specify the field_width, the default is 
equal to the character length of the data list item (after conversion, if necessary, 
according to the rules given in “Data Conversion” on page 5-27). 


For example: 
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GET FILE(INFILE) EDIT(ITEM) (A(20)); 


This statement assigns to ITEM the next 20 characters in the file, called INFILE. 
The value is converted from its character representation specified by the format item 
A(20) to the representation specified by the attributes declared for ITEM. 


You can also use the A-format item for input of numeric data containing such char- 
acters as currency symbols. For example: 


DECLARE CHARVARIABLE CHARACTER (5), 
PICVARIABLE PICTURE '$$$$3! 
BASED (POINTER1), 
POINTERI POINTER; 
POINTER1 = ADDR(CHARVARIABLE) ; 
GET EDIT (CHARVARIABLE) (A(5)); 


The GET statement causes the next five characters to be assigned to the 
CHARVARIABLE. The associated arithmetic value can then be accessed by 
means of PICVARIABLE. 


You can also use the A-format item for simple output of any problem data type, in 
which case the character representations of the data items are written. For example: 
DECLARE BINVARIABLE BINARY FIXED (15), 
DECVARIABLE DECIMAL FLOAT (10), 
PICVARIABLE PICTURE '999.99'; 
PUT SKIP EDIT 
(BINVARIABLE,DECVARIABLE, PICVARIABLE) (A,X(5)) 3 


The PUT statement writes the character representations of BINVARIABLE, 
DECVARIABLE, and PICVARIABLE, separating them by five blanks. 


B-, B1-, and B4-Format Items 


The bit format item describes a character representation of a bit value. You specify 
a bit format item as B, B1, or B4, depending on how the bit value is represented. 


For input: 


(field width)—»< 


(field_width) 
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B, BI 
Specify that the value of the data item is represented by the characters 0 and 1. 


B4 
Specifies that the value of the data item is represented in hexadecimal format. 


field_width 
An integer constant up to 32 767 that specifies the number of character posi- 
tions in the data stream that contain, or will contain, the representation of the 
bit value. 


On input, the character representation of the bit value can occur anywhere within 
the specified field. Blanks, which can appear before and after the bit value in the 
field, are ignored. Any necessary conversion occurs when the bit value is assigned to 
the data_list_item. 


The field width is always required on input; if it is zero, a null value is obtained. 
Any characters other than those valid for the specified representation (0 or 1 for B 
or B1 items, or the hexadecimal digits 0 to F for B4 items) raise the conversion 
condition. For example: 


DECLARE BITSTRING BIT (16) ALIGNED; 
GET EDIT (BITSTRING) (B4(4)); 


If the input stream contains the characters C1C2, the value of BITSTRING after 
the GET statement is processed is the binary equivalent of hexadecimal C1C2, that 
is, '1100000111000010'B. 


If you use the B4 format item to read data into a character variable, the bit data 
item is converted to character. For example: 


DECLARE CHARSTRING  CHARACTER(2); 
GET EDIT (CHARSTRING) (B4(4)); 


If the input stream contains the characters C1C2, the value of CHARSTRING after 
processing the GET statement is '11': the first and second bits of the character 
string C1C2, each of which has a value of one, are each converted to character '1', 
and the remaining fourteen bits are ignored because CHARSTRING can only 
contain two characters. 


On output, any necessary conversion to bit is processed. 


B4 items are assigned to the output field in multiples of four bits. If the converted 
value of the source is not a multiple of four, it is padded on the right with zeros up 
to the next multiple of four. For example: 


DECLARE MASK BIT (25) ALIGNED; 
PUT FILE (MASKFILE) EDIT (MASK) (B4) ; 


This PUT statement writes the value of MASK to the file MASKFILE as a string 
of seven hexadecimal characters, by padding MASK with three bits set to zero, 
producing a string of 28 bits (the next multiple of four). 

The character representation of the bit value is left-adjusted in the specified field, 


and any necessary truncation or extension with blanks occurs on the right. Neither 


Chapter 11. Input and Output Statements 11-33 


DATA SPECIFICATIONS 


apostrophes nor the identifying letter B (or B1 or B4) are inserted. If the 
field_width is zero, no characters are placed into the data stream. If you do not 
specify the field_width, the default is equal to the length of the data-list-item (after 
conversion, if necessary, according to the rules given in “Data Conversion” on 
page 5-27). For example: 

DECLARE MASK BIT (25) ALIGNED; 

PUT FILE (MASKFILE) EDIT (MASK) (B); 


This PUT statement writes the value of MASK to the file called MASKFILE as a 
string of 25 characters consisting of zeros and ones. 


COLUMN Format Item 


The COLUMN format item positions the file to a specified character_position 
within the current or following line. It can be used with input and output files. 


>>——COLUMN(character_position)——»« 


Abbreviation: COL for COLUMN 


character_position 
An integer constant up to 32 767. 


The file is positioned to the specified character_position in the current line, provided 
it has not already passed this position. 


If the file is already positioned after the specified character_position, the current line 
is completed and a new line is started; the format item is then applied to this new 
line. 


On input, intervening character positions are ignored. On output, they are filled 
with blanks. 


If the specified character_position is zero or lies beyond the rightmost 
character_position of the current line, the default character_position of 1 is used. 


The rightmost character_position is determined as follows: 


¢ For output files, it is equal to the line size. 
¢ For input files, it is equal to the length of the current logical record. 


E-Format Item 


The floating-point format item describes a character representation of a floating- 
point or fixed-point decimal data item. 
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p>>—E—(fiel ia rr ine 
»fractional_digits 


where: 


16 2 fractional_digits = 0 
and 


field_width 2 fractional_digits 


field_width 
An integer constant up to 32 767. It specifies the total number of characters in 
the field. 


fractional_digits 
An integer constant that specifies the number of digits that follow the decimal 
point. If you omit fractional_digits, it defaults to zero for input. For output, its 
value is derived from the type of data list item, as follows: 


Data List Item Type Fractional Digits 


Notes 
1. min(x,y) is the smaller of x and y. 
2. ceil(x) is the smallest integer larger than or equal to x. 
3. pl is the length of the bit string. 
4, p2 is the number of binary digits that appear in the value of the data list item. 
5 


. p3 is the number of binary digits that are declared or computed to be in the 
data list item. 


6. p4is the number of decimal digits that appear in the value of the data list item. 
7. p5 is the number of decimal digits that are declared or computed to be in the 


data list item. 


On input, the data value in the data stream is the character representation of an 
optionally signed decimal floating-point or fixed-point constant located anywhere 
within the specified field. It must conform to the following syntax: 


Chapter 11. Input and Output Statements 11-35 


DATA SPECIFICATIONS 


[+| -]significand+ 
[{E| E+|E-|+|-} integer] 


where significand is a decimal fixed-point constant. 
Blanks are ignored. They can appear before and after the data value in the field. 


The value of field_width includes leading and trailing blanks, the exponent position, 
the positions for the optional plus or minus signs, the position for the optional letter 
E, and the position for the optional decimal point in the significand. 


If no decimal point appears in the significand of the data value, fractional_digits 
specifies the number of character positions in the significand to the right of the 
assumed decimal point. If a decimal point does appear, it overrides the specification 
of fractional_ digits. 


On output, the data list item is converted to floating-point and rounded if necessary. 


The character string in the output stream has one of the following syntaxes: 
¢ For fractional_digits = 0 [-] 
digit E 
lS 
exponent 
The field_width must be > 6 for positive values, or > 7 for negative values. 
The value zero appears without a sign. 
¢ For fractional digits > 0 [-] 
digit.frac_digits E 
(+15 
exponent 
where frac_digits is a string of digits of length fractional_digits. 


The field_width must be > 7 + fractional_digits for positive values, or > 8 + 
fractional_digits for negative values. 


The leading digit in the significand is zero only if the value is zero. 


The exponent field is three characters long, and can appear in either of two forms, 
depending on the magnitude of the exponent value. The form nnb applies when the 
exponent value is in the range 0 to 99; two digits are followed by one blank. The 
form nnn applies when the exponent value exceeds 99. You should remember when 
defining output format that if your exponent is 99 or less, your E-format item will 
include a blank character following the exponent. Some examples of exponents are 
00b, 99b, 100, and 123. 


The conversion from internal decimal fixed-point to character is processed according 


to the normal rules for conversion. Extra characters may appear as blanks preceding 
the number in the converted string. And, since leading zeros are converted to 
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blanks (except for a zero immediately to the left of the decimal point), additional 
blanks may precede the number. A minus sign will replace one leading blank. 


Truncation of data values may occur during conversion (see “Truncation of 
Floating-Point Data” on page 5-34). 


It is an error if the field_width is such that the sign or any significant digit is trun- 
cated. 


For example: 
GET FILE(AUDIT) EDIT(COST) (E(10,6)); 


This statement obtains the next ten characters from the file called AUDIT and inter- 
prets them as a floating-point or fixed-point decimal number. A decimal point is 
assumed before the rightmost six digits of the significand, but an actual decimal 
point within the data overrides this assumption. The value of the number is con- 
verted to the attributes of COST and assigned to this variable. 


F-Format Item 


The fixed-point format item describes the character representation of a decimal 
fixed-point arithmetic data item. 


>>—F—(fiel — |. 
fractional_digits 


, 
where: 
127 2 fractional_digits 2 0 


and 


field_width = fractional_digits 


field_width 
An integer constant up to 32 767. It specifies the total number of characters in 
the field. 


fractional_digits 
An integer constant that specifies the number of digits that follow the decimal 
point. If you omit fractional_digits, it defaults to zero. 


On input, the data value in the data stream is the character representation of an 
optionally signed fixed-point decimal constant located anywhere within the specified 
field. Blanks before and after the data value in the field are ignored. If the entire 
field is blank, it is interpreted as zero. 


The value of field_width includes leading and trailing blanks, the position for the 
optional plus or minus sign, and the position for the optional decimal point. 
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If no decimal point appears in the data value, fractional_digits specifies the number 
of digits in the data item to the right of the assumed decimal point. If a decimal 
point does appear, it overrides the specification of fractional_digits. 


On output, the data list item is converted, if necessary, to fixed-point decimal, 
according to the conversion rules given in “Data Conversion” on page 5-27. 


The data value in the stream is the character representation of a fixed-point decimal 
number, right-adjusted in the specified field. 


The field_width must be large enough to hold the character representation of the 
value. The following conditions apply to the field_width: 
¢ For fractional_digits = 0 
field width > | 
for positive values, or 
field_width = 2 
for negative values. 
¢ For fractional_digits > 0 
field_width >= fractional_digits + 2 
for positive values, or 
field_width > fractional_digits + 3 
for negative values. 
This allows for a decimal point and at least one digit to the left of the decimal 


point. 


If fractional_digits is zero, only the integer portion of the number is written; no 
decimal point appears. 


If fractional_digits is greater than zero, both the integer and fractional portions of 
the number are written, and a decimal point is inserted before the rightmost digit 
position specified by fractional_digits. Trailing zeros are supplied when the scale 
factor is less than the number of fractional digits of the data item after any necessary 
conversion. If the absolute value of the item is less than 1, a zero precedes the 
decimal point. Leading zeros are suppressed in all digit positions (except the first) 
to the left of the decimal point. 


Truncation of data values may occur during conversion (see “Truncation of 
Floating-Point Data” on page 5-34). 


The conversion from internal decimal fixed-point to character is done according to 
the normal rules for conversion. Extra characters may appear as blanks preceding 
the number in the converted string. And, since leading zeros are converted to 
blanks (except for a zero immediately to the left of the decimal point), additional 
blanks may precede the number. A minus sign will replace one leading blank. 


For example: 
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DECLARE TOTAL FIXED DECIMAL (4,2); 
PUT EDIT (TOTAL) (F(6,2)); 


The PUT statement specifies that the value of TOTAL is to be converted to the 
character representation of a decimal fixed-point number and written into the output 
file SYSPRINT. A decimal point is to be inserted before the last two digits, and the 
number will be right-adjusted in a field of six characters. Leading zeros will be 


changed to blanks (except for a zero immediately to the left of the decimal point), 
and, if necessary, a minus sign will be placed to the left of the first digit. 


LINE Format Item 


The LINE format item specifies the particular line on the current page of a print file 
to which the next data list item is transmitted. 


>>—LINE(line_number)—->< 


line_number 
An integer constant up to 32 767. 


Blank lines are inserted, if necessary, to do the positioning. 


The ENDPAGE condition is raised if the specified line_number is: 


e Less than the current line_number 
e Equal to the current line_number and the current line contains data 
e Greater than the limit set by the PAGESIZE option. 


PAGE Format Item 


The PAGE format item specifies to start a new page. It can be used only with print 
files. 


>>——PAGE—_*< 


Starting a new page positions the file to line 1. 


SKIP Format Item 


The SKIP format item specifies a new line for a print file, or a new record for a 
non-print file. 


al SE 
(relative line) 
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relative_line -) 
An integer constant up to 32 767. It specifies the number of the line (relative to 
the current line) to skip to. Relative_line must be greater than zero for input 
files and non-print output files, and greater than or equal to zero for print files. 
For a print file, SKIP(0) means that characters are written on the current line, 
overwriting characters already written. If you omit relative line, the default is 1. 


The file is positioned at the start of the specified line relative to the current line, 
unless the ENDPAGE condition is raised. For print files, the ENDPAGE condi- 
tion is raised if the position of the specified relative line is beyond the limit set by 
the PAGESIZE option of the OPEN statement (or by default). 


If the SKIP format item is the first format item processed after a file has been 

opened, the file is positioned to the first column of the specified line relative to the 
first line. For example, SKIP (0) would position the file at the first line; SKIP (1) 
would position the file at the second line, and so on. > 


X-Format Item 


The spacing format item controls the spacing of data values in the data stream. 


mamas 
field_width ; 


An integer constant up to 32 767. It specifies the number of characters in the 
data stream between the current position in the stream and the start of the next 
data field your program will process. 


On input, the specified number of characters are bypassed in the data stream and 
not transmitted to the program. For example: 


GET EDIT(NUMBER,REBATE) (A(5),X(5),A(5)); 


This statement treats the next 15 characters from the input file, SYSIN, as follows: 
the first five characters are assigned to NUMBER, the next five characters are - 
bypassed, and the remaining five characters are assigned to REBATE. 


On output, the specified number of blank characters are inserted into the stream. 
For example: 
PUT FILE(OUT) EDIT(PART, COUNT) 
(A(4) ,X(2) ,F(5))5 
This statement places, in the file named OUT, four characters that represent the 


value of PART, then two blank characters, and finally five characters that represent 
the decimal fixed-point value of COUNT. 
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Transmission of Array Elements and Structure Fields 


If a data_list_item is a multi-dimensional array, the array elements are transmitted in 
row-major order; that is, with the rightmost subscript of the array varying most fre- 
quently. Consider the following example: 


DECLARE SAMPLEARRAY (2,2,2) FIXED BINARY (15); 


The elements of the array are transmitted in the following order: 


NOON NN NN NN 
PO Po Po PO FR Rr re 


If a data_list_item is a structure, the structure fields are transmitted in the order 
specified in the structure declaration. 


For example: 


DECLARE 1 ARAY (10), 
2 BFID FIXED DECIMAL(3), 
2 CFID FIXED DECIMAL(3); 


PUT FILE(XFIL) EDIT(ARAY) (F(3))s 


produces output ordered as follows: 


ARAY.BFID(1) ARAY.CFID(1) 
ARAY.BFID(2) ARAY.CFID(2) 
ARAY.BFID(3) ARAY.CFID(3) 


However, if the declaration is: 


DECLARE 1 ARAY, 
2 BFID(10) FIXED DECIMAL(3), 
2 CFID(10) FIXED DECIMAL(3); 


PUT FILE(XFIL) EDIT(ARAY) (F(3)); 


the result is ordered as follows: 


ARAY.BFID(1) ARAY.BFID(2) ... ARAY.BFID(10) 
ARAY.CFID(1) ARAY.CFID(2) ... ARAY.CFID(10) 


If, within a data list, a variable is assigned a value, this new value is used if the vari- 
able appears in a later reference in the data list. For example: 
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GET EDIT (N,(X(1) DO I=1 TO N))(F(3)); 


When this statement is processed, values are transmitted and assigned as follows: 
1. A new value is assigned to N. 


2. Elements are assigned to the array X as specified in the iterative specification in 
the order X(1),X(2),...X(N), with the new value of N being used to specify the 
number of items assigned. 


The following examples show the use of the COLUMN, LINE, PAGE, and SKIP 
format items in combination with one another: 


PUT EDIT ("QUARTERLY STATEMENT’) 
(PAGE, LINE(2), A(19)); 

PUT EDIT (ACCT#, BOUGHT, SOLD, 
PAYMENT, BALANCE) 
(SKIP(3), A(6), COLUMN(14), 
F(7,2), COLUMN(30), F(7,2), 
COLUMN(45), F(7,2), 
COLUMN(60), F(7,2)); 


The first PUT statement specifies that the heading QUARTERLY STATEMENT 
is to be written on line two of a new page in the output file SYSPRINT. The 
second statement specifies that two lines are skipped (that is, “skip to the third fol- 
Jowing line”) and the value of ACCT# is to be written, beginning at the first char- 
acter of the fifth line; the value of BOUGHT is to begin at character position 14; 
the value of SOLD is to begin at character position 30; the value of PAYMENT is 
to begin at character position 45; and the value of BALANCE is to begin at char- 
acter position 60. 


You can control the layout of a print file by means of the options and format items 
listed in Figure 11-2. 


Statement Format Effect 
Item 


OPEN LINESIZE(expression) Establishes line width 


PAGESIZE(expression) Establishes page depth 


Figure 11-2 (Part 1 of 2). Options and Format Items for Print Files 
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Format 
Item 
PAGE Skip to new page 


LINE(expression) LINE(n) Skip to specified line 


SKIP[(expression)| SKIP[(n)] Skip specified 


number of lines 


COLUMN(n) | Skip to specified 
COL(n) character position 
in line 


X(n) Skip the specified 
number of characters 


Figure 11-2 (Part 2 of 2). Options and Format Items for Print Files 


Note: 7 1s an integer constant. 


LINESIZE and PAGESIZE establish the dimensions of the printed area of the 
page, excluding footings. For example: 


DECLARE REPORT FILE STREAM PRINT, 
N FIXED DECIMAL (3) 
STATIC INITIAL(0); 
OPEN FILE(REPORT) PAGESIZE(55) 
LINESIZE(110); 
ON ENDPAGE(REPORT) 
BEGIN; 
PUT FILE(REPORT) SKIP(2) EDIT 
(FOOTING) (A(B)); 
N=N+4+13 
PUT FILE(REPORT) PAGE EDIT 
("PAGE',N) (A,X(1) ,F(3)) 5 
PUT FILE(REPORT) SKIP (3); 
END; 


The OPEN statement opens the file REPORT as a print file. The specification 
PAGESIZE(55) indicates that each page should contain a maximum of 55 lines, 
excluding the footing. After 55 lines have been written (or skipped), the next line 
written or skipped will raise the ENDPAGE condition and process the begin-block. 
Because the ENDPAGE condition is raised only once for each page, printing con- 
tinues beyond the specified PAGESIZE. 


LINESIZE(110) indicates that each line on the page can contain a maximum of 110 
characters. If you attempt to write a line greater than 110 characters, the excess 
characters are placed on the next line. 


The first PUT statement in the begin-block specifies line skipping so that the value 


of FOOTING, presumably a character value, is to be printed on line 58 (when 
ENDPAGE 1s raised, the current line is always PAGESIZE+ 1). The page number, 
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SYSIN File 


SYSPRINT File 


N, is incremented, the file is positioned to the next page, and the character constant 
'PAGE'! 1s printed together with the new page number. The final PUT statement 
specifies line skipping so that the file is positioned to line 4. Control returns from 
the on-unit to the PUT statement that raised the ENDPAGE condition. Any SKIP 
or LINE option specified in that statement, however, has no further effect. 


The file SYSIN, if not explicitly declared or opened, has the default attributes FILE, 
STREAM, INPUT, and EXTERNAL, and 1s associated with the AS/400 file 
named QINLINE in the AS/400 library named QGPL. 


If file SYSIN is explicitly declared with the EXTERNAL attribute, it is associated 
with the AS/400 file named QINLINE in the AS/400 library named QGPL. If file 
SYSIN is explicitly declared with the INTERNAL attribute, it is associated with a 
AS/400 file named SYSIN, which you must create. 


You must use SYSIN in a way that 1s compatible with its use by the compiler. See 
“Considerations for Opening a Print Stream File” on page 7-12. 


The file SYSPRINT is given the attribute PRINT when it is opened, provided that 
it has the STREAM, OUTPUT, and EXTERNAL attributes. SYSPRINT uses the 
program name for computer output modules. 


A new page is started automatically when the file is opened. If the first PUT state- 
ment that refers to the file has the PAGE option, or if the first PUT statement 
includes a format list with PAGE as the first item, a blank page will appear. 


If SYSPRINT is not explicitly declared or opened, it has the default attributes 
PRINT, FILE, STREAM, OUTPUT, and EXTERNAL, and is associated with the 
AS/400 file named QPRINT in the AS/400 library named QGPL. 


If file SYSPRINT is explicitly declared with the INTERNAL attribute, it is associ- 
ated with an AS/400 file named SYSPRINT, which you must create. 


11-44 PL/I User’s Guide and Reference 


THE DECLARE STATEMENT 


Chapter 12. Declaring Names and Attributes of Variables 


This chapter describes the DECLARE statement and its attributes. 


The DECLARE Statement 


You use the DECLARE statement to explicitly declare the names and attributes of 
variables. You can declare many variables with a single DECLARE statement. 


You can use the DECLARE statement as part of the documentation of your 
program by specifying all the attributes of a name, even when attributes may be 
added by default, or by implicit or contextual declaration. You can factor attributes, 
as described under “Factoring of Attributes” on page 12-2. 


ee 
an i a name attribute :—_>< 
level | 


el 
(——name ) 


Abbreviation: DCL for DECLARE. 


level 
An integer constant in the range | through 255. It specifies the level number of 
a structure or of a field contained in a structure (see “Structures and Level 
Numbers” on page 12-39). 


name 
The name or names being declared. If you want to declare more than one 
name, see “Factoring of Attributes” on page 12-2. 


attribute 
All attributes you want to specify for a name must appear in a single 
DECLARE statement. There can be up to 9999 attributes in a declare state- 
ment. You need not declare any default attributes or implied attributes (see 
“Classification of Attributes” on page 12-2). You can provide the attributes of 
a variable or a named constant by explicit declaration, by default, or, in the case 
of built-in function names and built-in subroutines, by context (see “Names” on 
page 4-12). 


A DECLARE statement cannot have a label. 
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Factoring of Attributes J 


You can factor attributes common to several names to avoid repeated specification 
of the same attribute. 


To factor attributes, enclose the names of the variables, separated by commas, in 
parentheses, and follow the parenthesized list by the set of attributes that apply to 
all of the names. Only identifiers are valid in the parenthesized list. 


Factoring cannot be nested; that is, you can only specify one level of parentheses. 


Examples of factoring are: 
DECLARE (A,B,C,D) BINARY FIXED (31); 


DECLARE 1 A, 2(B,C,D) (3,2) BINARY FIXED (15); 


Classification of Attributes 
The attributes are classified by the type of data they represent. 


The two types of data in a PL/I program are: 


¢ Problem data, which represents values processed by the program. It consists of 

coded arithmetic, bit, character, and picture data (see “Problem Data 

Attributes” on page 12-9). ) 
¢ Program control data, which is used to control the processing of the program. 


It consists of pointer, label, entry, and file data (see “Program Control Data 
Attributes” on page 12-30). 


Figure 12-1 on page 12-3 shows you how to specify attributes for all the types of 
data. 


The rest of this chapter presents the classification, syntax diagrams, and descriptions 


of the attributes. ) 
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CLASSIFICATION OF ATTRIBUTES 


Key 
RECORD must be declared implicitly 
STREAM default attribute 
default path 
[= XE comment 
Footnotes: 


1Only one base or one scale attribute must be specified. The default value then 
applies for the other. 


*UNALIGNED cannot be specified with DECIMAL FIXED. 
3ALIGNED must be specified with BIT. 
*ALIGNED can only be specified if VARYING is also specified. 
>You cannot specify the dimension attribute for an entry constant. 
°For more information on the ENVIRONMENT attribute, see “The ENVI- 
RONMENT Attribute” on page 7-1. 
Additional Notes: 

1. Attributes may be specified in any order, except for the following restrictions: 
¢ The dimension attribute must immediately follow the name or name-list. 
¢ The precision attribute must immediately follow the base or scale attribute. 

2. The following restrictions apply to structures: 


e For a major structure name, you can specify any of the scope and storage 
attributes, except for INITIAL. 


¢ For a minor structure name, you cannot specify any attributes. 


¢ For a field name, you can specify only the data and alignment attributes, 
and the INITIAL attribute. 


3. The default precisions for coded arithmetic data are shown in “Precision 
Attribute” on page 12-10. The default string length for string data is 1. 


4. The implied attributes are listed under “Implied Attributes” on page 12-5. 


5. Label constants and internal entry constants cannot be declared with a 
DECLARE statement. 


6. For structures, INTERNAL and EXTERNAL should be declared in level 1 
declarations only. An error message is sent if a member of a structure has a 
scope specified that is different from the scope specified in the level 1 declara- 
tion. 


How To Use The Table 
Any line through the attributes in this table contains a complete set of the attributes 


fora name. By proceeding through the table, from top to bottom, you may select a 
valid combination of attributes for any line. 
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¢ Attributes shown in boldface must be declared explicitly (in a DECLARE state- 
ment) or implicitly (through the use of another attribute, option or statement). 
The first attribute in boldface on any line is required if you want any attributes 
on that line. 


¢ Default attributes are underlined. They are selected for you, on the default 
path, unless you specify any alternative attributes (shown as branches from the 
default path). 


e All other attributes are optional. You must specify them if you want the 
declared name to have that particular attribute. 


e Exceptions to these points are discussed in the footnotes and additional notes. 


Required Attributes 


Implied Attributes 


Except for major or minor structure names, you must declare at least one of the 
following attributes for each name in a DECLARE statement: BINARY, 
DECIMAL, FIXED, FLOAT, BIT, CHARACTER, PICTURE, POINTER, 
LABEL, ENTRY, FILE, or BUILTIN. 


When you declare some attributes, you may imply others. You do not have to 
declare these attributes, but, just as with default attributes, you can declare them if 
you wish. 


The attributes you specify and the attributes they imply are: 


RECORD 
RECORD 
RECORD 


RECORD, KEYED 


EXTERNAL, OUTPUT, 
STREAM 


ENVIRONMENT | ENVIRONMENT 
(KEYDISP (INDEXED) 
KEYLENGTH) 


For the file attributes that are implied by implicit opening of a file, see “Implicit 
Opening” on page 11-6. 
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File Attributes 


A name that represents a file must have the FILE attribute. Such a name is a file 
constant. The characteristics of each file are described with keywords called file 
description attributes. 


The file description attributes are either alternative attributes or additive attributes. 
An alternative attribute is chosen from a group of attributes. If no explicit or 


implied attribute is given for one of the alternatives in a group, and if one of the 
alternatives is required, the default attribute is used. 


PL/I provides the following three groups of alternative file description attributes (the 
default attributes are underlined): 


RECORD|STREAM 
INPUT|OUTPUT|UPDATE 
SEQUENTIAL|DIRECT 


An additive attribute must be stated explicitly or may be implied by another explic- 
itly stated attribute. 


The additive attributes are: 
KEYED 

PRINT 

ENVIRONMENT (option_list) 


For a list of which file description attributes imply others, see “Implied Attributes” 
on page 12-5. 


Some file description attributes can be specified in an OPEN statement or implied 
by an implicit opening (see “Implicit Opening” on page 11-6). 


You can also specify scope and storage attributes (excluding INITIAL), but the 
default scope value is EXTERNAL. You cannot specify VARIABLE or include a 
file constant in an aggregate (see Figure 12-1 on page 12-3). 


The syntax of the FILE attribute and the file description attributes is: 
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$ 


ENVIRONMENT (option_list) 


Abbreviations: SEQL for SEQUENTIAL 
ENV for ENVIRONMENT 


FILE Attribute 
The FILE attribute indicates that the associated name is a file constant. 


Each file name must be explicitly declared with the FILE attribute. 


RECORD and STREAM Attributes 
The RECORD and STREAM attributes specify the type of data transmission 
used for the file. 


The UPDATE, SEQUENTIAL, DIRECT, KEYED, and ENVIRONMENT 
attributes can only be used with the RECORD attribute. 


The PRINT attribute can only be used with the STREAM attribute. 


INPUT, OUTPUT, and UPDATE Attributes 
The INPUT, OUTPUT, and UPDATE attributes determine the direction of 
data transmission permitted for a file. UPDATE must not be used with 
STREAM. 


SEQUENTIAL and DIRECT Attributes 
The SEQUENTIAL and DIRECT attributes describe how the records in the 
file are accessed. 


The SEQUENTIAL and DIRECT attributes apply only to a file with the 
RECORD attribute. 


KEYED Attribute 
The KEYED attribute indicates that records in the file can be accessed by 
means of one of the key options (KEY, KEYTO, or KEYFROM) of data 
transmission statements or of the DELETE statement. 


The KEYED attribute applies only to a file with the RECORD attribute. 


PRINT Attribute 
The PRINT attribute indicates that the file is intended for printing; that is, the 
data associated with the file is to appear on printed pages, although it may first 
be written on some other device. 
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The PRINT attribute applies only to files with the STREAM and OUTPUT ) 
attributes. 


ENVIRONMENT Attribute 
The options list of the ENVIRONMENT attribute is implementation-defined. 
It specifies file characteristics that are not part of the PL/I language. — 


>>— ENVIRONMENT—— 


EXCLR 


iio lett a 
aie) Daal ees 
an IS ic are 7 ee ce 
COMMITTABLE BLOCK: NOINDARA ai 


Abbreviation: ENV for ENVIRONMENT 


Options in the option-list are separated by blanks or commas. The options are 
described in “The ENVIRONMENT Attribute” on page 7-1 and summarized 
in Figure 7-2 on page 7-9. 


ENVIRONMENT(CONSECUTIVE) is the default value if you do not specify 
the ENVIRONMENT attribute. | ) 


Do not specify the ENVIRONMENT attribute and the STREAM attribute for 
the same file. 


For a discussion of using file data and the file description attributes for record 
input/output, see “Use of File Description Attributes” on page 11-9. For a dis- 
cussion of using file data and the file description attributes for stream 
input/output, see “File Description Attributes” on page 11-23. 


Data Types 
The types of data in a PL/I program are: 


¢ Problem data, which represents values processed by the program. It consists of 
coded arithmetic, string, and picture data (see “Problem Data Attributes” on 
page 12-9). 
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¢ Program control data, which is used to control the processing of the program. 
It consists of pointer, label, entry, and file data (see “Program Control Data 
Attributes” on page 12-30). 


For example, the statement: 
AREA = RADIUS**2 * 3.1416; 


contains problem data variables and constants. AREA and RADIUS are variables, 
and the numbers 2 and 3.1416 are constants. 


If you want to use the number 3.1416 in more than one place in a program, it may 
be more convenient to represent it as a variable to which you assign the value 
3.1416. Therefore, the above statement could be written as: 


PI = 3.1416; 
AREA = RADIUS**2 * PI; 


In the last statement, only the number 2 is a constant. 


The following program segment contains a program control data constant or named 
constant called LOOP: 


SAMPLE: PROCEDURE OPTIONS (MAIN); 
DECLARE (ITEM1,ITEM2) FIXED DECIMAL (2); 
DECLARE ITEM3 FIXED DECIMAL (3); 
DECLARE EOF BIT (1) ALIGNED 
INITIAL ('8'B) STATIC; 
ON ENDFILE (SYSIN) EOF = '1'B; 
GET EDIT (ITEM1,ITEM2) (COL(1),F(2),F(2)); 
LOOP: DO WHILE (EOF = '0'); 
ITEM3 = ITEM1 + ITEM2; 
PUT EDIT (ITEM3) (COLUMN(10) ,F(3)); 
GET EDIT (ITEM1,ITEM2) (COLUMN(1),F(2),F(2)); 
END LOOP; 
END SAMPLE; 


The name LOOP is declared as a label constant by its appearance as a label prefix. 
The value of the constant identifies the labeled statement, within a particular acti- 
vation of the block containing this statement. 


Problem Data Attributes 


Problem data consists of coded arithmetic, string, and picture data. 


VARIABLE can be specified for all problem data. It is the default value. 
INTERNAL is the default scope value. 


Problem data can always be grouped into aggregates by specifying a dimension or 
by using structures. 
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Coded Arithmetic Data Attributes 
The types of coded arithmetic data attributes are base, scale, and precision. 


Each coded arithmetic variable must be declared with at least a base or a scale attri- 
bute. You may also specify precision, UNALIGNED (except with DECIMAL 
FIXED), VARIABLE, scope and storage attributes, but default values apply if you 
do not specify any of these. Default values are shown in Figure 12-1 on page 12-3. 
You can always group coded arithmetic variables into aggregates. 


Base Attributes 


The base of an arithmetic data item is either binary or decimal. 


DECIMAL 


Abbreviations: BIN for BINARY 
DEC for DECIMAL 


Scale Attributes 


The scale of an arithmetic data item is either fixed-point or floating-point. 
FLOAT 


Precision Attribute 


The precision of a fixed-point data item is the number of digits the data item can 
have. The precision of a floating-point data item is the minimum number of signif- 
icant digits (excluding the exponent). For decimal fixed-point data, the precision 
attribute may include the scale factor (the assumed position of the decimal point, 
relative to the rightmost digit of the number). 


The syntax for fixed-point precision 1s: 


>>—(number_of_digits )—< 
Lnscbleciaan 


The syntax for floating-point precision 1s: 


>>—(number_of_digits)—»< 
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number_of_digits 
An integer constant that specifies the number of digits (both integers and frac- 
tional digits) maintained for data items assigned to the variable. For BINARY 
variables, it specifies the number of bits. For DECIMAL variables, it specifies 
the number of decimal digits. 


scale_factor 
An integer constant that specifies the number of fractional digits for fixed-point 
data. 


For decimal fixed-point data, the scale factor must be in the range 0 through 15. 
The scale factor must not exceed the number of digits. If you specify a scale 
factor for binary fixed-point data, it must be 0. 


The precision attribute must immediately follow the base or scale attribute. 


The maximum number of digits allowed and the default precisions for each data 
type are shown in the table below. 


Data Maximum | Default 
type digits precision 
DECIMAL 15 (5,0) 
FIXED 

BINARY 3] (15) 
FIXED 

DECIMAL 16 (7) 
FLOAT 

BINARY 53 (24) 
FLOAT 


The maximum length restrictions hold for declared precisions and for the precision 
of a constant. 


The precision attribute is often represented as (p) or (p,q), where p represents the 
number of digits, g represents the scale factor, and p is greater than or equal to g. 


Decimal Fixed-Point Data 


A decimal fixed-point value is a rational number, regarded as a sequence of decimal 
digits with an assumed position of the decimal point. 


A decimal fixed-point constant consists of one or more decimal digits with an 
optional decimal point. If you omit the decimal point, it is assumed to be imme- 
diately to the right of the rightmost digit. The precision of a decimal fixed-point 
constant is (p,q), where p is the total number of digits in the constant and q is the 
number of digits to the right of the decimal point; q = 0 if there is no decimal 
point. q must be less than or equal to p. 


Examples of decimal fixed-point constants and their precisions are: 
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Constant Precision 


3.1416 (5,4) 
455.3 (4,1) 
732 (3,0) 
003 (3,0) 
5280 (4,0) 
0012 (4,4) 


You declare a decimal fixed-point variable with the DECIMAL, FIXED, and preci- 
sion attributes. A variable declared as DECIMAL FIXED (p,q) can hold values 
represented by p decimal digits, q of which are to the right of the assumed decimal 
point. For example: 


DECLARE VARIABLE1 FIXED DECIMAL (5,4); 


DECLARE VARIABLE2 FIXED DECIMAL (3,0); 


These DECLARE statements specify that VARIABLE1 and VARIABLE2 are 
decimal fixed-point variables with values in the range -9.9999 through + 9.9999, and 
-999 through +999 respectively. A value assigned to VARIABLE] or 
VARIABLE2 is converted to decimal fixed-point and aligned on the decimal point. 


If the value 1.22229 is assigned to VARIABLE]! and VARIABLE2, the resulting 
value of VARIABLE] 1s 1.2222 and the resulting value of VARIABLE2 1s 001. If 
the value assigned is 123.999, the resulting value of VARIABLE] is undefined 
because it is too large; the FIXEDOVERFLOW condition will also be raised. The 
resulting value of VARIABLEZ2 is 123. 


Decimal fixed-point data is represented in storage as packed decimal. Packed 
decimal data is stored two digits to the byte. The nghtmost byte holds only one 
digit; its rightmost four bits hold the sign indication. Consequently, a decimal fixed- 
point data item with an even number of digits contains zeros in the leftmost four 
bits of the leftmost byte. 


Binary Fixed-Point Data 


A binary fixed-point value is an integer, regarded as a sequence of binary digits. 
(Binary fixed-point data always has a scale factor of zero.) 


There are no binary fixed-point constants. 
You declare a binary fixed-point variable with the BINARY, FIXED, and precision 


attributes. A variable declared as BINARY FIXED (p) can hold integers repres- 
ented by p binary digits. For example: 


DECLARE FACTOR BINARY FIXED (20); 


In this example, FACTOR is to represent binary fixed point data items with a preci- 
sion of 20 binary digits. 
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A binary fixed-point data item requires either a halfword or word of storage. A 
halfword contains 15 binary digits plus a sign bit, and a word (sometimes called a 
fullword) contains 31 binary digits plus a sign bit. Any binary fixed-point data item 
with a precision of 15 or less is stored as a halfword. Any binary fixed-point data 
item with a precision greater than 15, up to the maximum precision of 31, is stored 
as a fullword. The maximum value of a binary fixed-point data item is 2!*>— 1 (or 
32 767) for the halfword form, and 27! — 1 (or 214483647) for the fullword form. 
Negative values are stored in “two’s complement notation.” The declared number of 
digits begins from the low-order positions. 


Decimal Floating-Point Data 


A decimal floating-point data item is an approximation of a real number, and con- 
sists of a sign, a significand, and an exponent. Its value is the signed product of (a) 
its significand, and (b) 10 raised to the power of its exponent. 


A decimal floating-point constant consists of a decimal fixed-point constant (that 
corresponds to the significand), followed by the letter E, followed by an optionally 
signed decimal integer constant (that corresponds to the exponent). The precision 
of a decimal floating-point constant is taken to be the number of digits in the 
significand. Examples of decimal floating-point constants and their precisions are: 


Constant Precision 
15E-23 (2) 
15E23 (2) 
4E-3 (1) 
0.4E-2 (2) 
1.96E + 07 (3) 
438E0 (3) 
3141593E-6 (7) 


.003141593E3 (9) 
The last two examples represent the same value. 


You declare a decimal floating-point variable with the DECIMAL, FLOAT, and 
precision attributes. A variable declared as DECIMAL FLOAT (p) can represent 
real numbers with a precision of p significant decimal digits. For example: 


DECLARE LIGHTYEARS DECIMAL FLOAT (5); 


In this example, LIGHTYEARS is to represent decimal floating-point data items 
with a precision of 5 significant decimal digits. 


The maximum precision allowed for decimal floating-point variables is 16; the 
default precision is 7. 


If you declare a floating-point variable with a precision less than or equal to 7, the 
value is represented internally in short format. If greater than 7 and less than or 
equal to 16, the value is represented internally in long format. Short and long 
floating point formats are described below. 
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Binary Floating-Point Data J 


A binary floating-point data item 1s an approximation of a real number, and consists 
of a sign, a significand, and an exponent. Its value is the signed product of (a) its 
significand, and (b) 2 raised to the power of its exponent. 


There are no binary floating-point constants. 


You declare a binary floating-point variable with the BINARY, FLOAT, and preci- 
sion attributes. A variable declared as BINARY FLOAT (p) can represent real 
numbers with a precision of p significant binary digits. In the following example, 


DECLARE TRIALNO FLOAT (16); 


TRIALNO represents a binary floating-point data item with a precision of 16 binary 
digits in the significand. ) 
Note: BINARY is the default attribute, if you do not specify a base attribute. } 


The maximum precision allowed for binary floating-point data items is 53; the 
default precision is 24. 


If you declare a floating-point variable with a precision less than or equal to 24, the 

value is represented internally in short format; if the precision is greater than 24 and 

less than or equal to 53, the value is represented internally in long format. Short 

and long floating-point formats are described below. “a 


Internal Representation of Floating-Point Data 


A floating-point number is represented in the AS/400 storage as a bit string con- 
sisting of three parts. The left part represents the sign of the number, the middle 
part represents the exponent of the number, and the right part represents the 
significand of the number. Its value relative to a binary base can be expressed in the 
form: 


(sign) (signi ficand) * (2) ** (exponent) j 


where * and ** denote the multiplication operator and the exponentiation operator 
respectively. 


The representation of a floating-point number can be in either of two formats. The 
short format stores in four bytes any number whose magnitude is within the range 
of (2**-126) to ((2-2**-23)*2**127), or approximately 10**-38 to 10**38. The long 
format stores in eight bytes any number whose magnitude is within the range of 
(2**-1022) to ((2-2**-52)*2**1023), or approximately 10**-308 to 10**308. The 
signed zero number can also be stored using both formats. 


The sign of the number is represented by a single bit. A zero indicates a positive 
sign, and a one indicates a negative sign. 


The exponent of the number is represented by eight bits if short format or eleven 


bits if long format. This set of bits is treated as a binary integer. The exponent ; 
value is adjusted prior to being stored by adding 127 if short format or 1023 if long . 
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format. This means that the sign of the exponent does not have to be stored. This 
means that the exponent value is in the range 1 to 254 if short format, or 1 to 2046 
if long format and it can be treated as unsigned. A stored exponent value of 0 
serves to identify the signed zero value. A stored exponent value of 255 for short 
format or 2047 for long format, together with certain significand values, serves to 
identify two symbolic number values, signed infinity and “not a number (NaN).” 


The significand of the number is represented by 23 bits if short format or 52 bits if 
long format. This set of bits is treated as a binary integer. In the case of the signed 
zero value, the significand is zero. 


The supported ranges of floating-point numbers are applicable when a floating-point 
number is stored in normalized form. A floating-point number is always stored in 
normalized form when an operation that produces a floating-point result is success- 
fully processed. A floating-point result is normalized just prior to being stored. 
Normalization involves shifting the significand to the left while decrementing the 
exponent until the leading significand bit becomes one; this leading one bit is then 
dropped before storing the significand, since its presence is implied. 


After a floating-point number has been normalized, the exponent value is checked 
to determine if it 1s outside the range allowed in the format of the result field: if it is 
below the minimum limit, a floating-point underflow condition is raised; if it is 
above the maximum limit, a floating-point overflow condition is raised. 


String Data Attributes 


String data attributes refer to either character data or bit data. A string is a contig- 
uous sequence of characters or bits that is treated as a single data item. 


You must specify BIT or CHARACTER. You can use the VARYING attribute to 
indicate varying-length character strings. You cannot specify VARYING for bit 
strings. You may also specify alignment (with the restrictions shown in Figure 12-1 
on page 12-3), VARIABLE, scope and storage attributes. Default values for these 
are shown in Figure 12-1 on page 12-3. String data can be grouped into aggregates. 


The syntax of the string data attributes 1s: 


CHARACTER 
| (length) VARY ING 
BIT 
(length) 


where 'length' is: 


* 
-—eonstant 
scalar_variable 


Abbreviations: CHAR for CHARACTER 
VAR for VARYING 
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BIT and CHARACTER Attributes 


The BIT attribute declares a variable that can hold bit values of a given length. The 
CHARACTER attribute declares a variable that can hold character values of a 
given length. 


length 
Specifies the length of a string. The default length is 1. The maximum length 
of a bit or nonvarying character variable is 32 767; the maximum length of a 
VARYING character variable is 32 765. The minimum length of a bit or char- 
acter variable is zero. Specify the length of a bit variable by number of bits, and 
the length of a character variable by number of characters. 


Specify the length attribute as follows: 


e Ifthe variable is static, based, or a member of a structure, the length must 
be an integer constant. 


e If the variable is automatic, the length must be an integer constant or a 
non-based scalar variable. If the variable is automatic, you must ensure that 
storage is currently allocated to it at the time you declare the bit or char- 
acter string using the variable to specify the length of the string. 


¢ If the variable is a parameter in an internal procedure, or a parameter 
descriptor in an ENTRY declaration, the length must be an integer constant 
or an asterisk. The asterisk indicates that the parameter will have the length 
of the corresponding argument passed by the calling procedure. 


All bit variables must have the ALIGNED attribute. If you do not specify 
ALIGNED, the compiler assumes ALIGNED and generates a warning message. 


Bit Data 


A bit value is a sequence of binary digits stored in consecutive bits. The storage for 
a declared bit variable, including each element of a bit array, always starts at a byte 
boundary. 


A bit constant is either a series of binary digits enclosed in apostrophes and followed 
immediately by B or B1, or a series of hexadecimal digits enclosed in apostrophes 
and followed immediately by B4. The value of a B or B1 constant is the string 
consisting of the binary digits between the enclosing apostrophes. The value of a 
B4 constant is the string obtained by converting each hexadecimal digit to a 4-digit 
binary number as shown in the table below. A bit constant has the attribute 
BIT(n), where n is the length of the bit value represented by the constant. 
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Hexadecimal Binary 
Digit Digits 
(B4) (B or BI) 


0 
l 
2 
3 
4 
5 
6 
7 
8 
9 
A 
B 
C 
D 
E 
F 


Figure 12-2. Hexadecimal Digits, and the Binary Equivalents 


The maximum length of a bit constant (including apostrophes and the B, B1, or B4 
characters) is 512 characters. 


A null bit constant is two consecutive apostrophes, followed immediately by B, B1, 
or B4. Its value is the null bit string. 


Examples of bit constants and the lengths of the represented bit values are: 


Constant Length 


'1'B (1) 
'11111010110001'B (14) 
1IB (0) 
'10100011'B (8) 
'10100011'B1 (8) 
'A3'B4 (8) 


In the last three examples, the values are the same. 


You declare a bit variable with the BIT attribute and a length specification. For 
example: 


DECLARE SYMPTOMS BIT (64) ALIGNED; 
In this statement, SYMPTOMS represents bit values 64 bits long. 


You must declare all bit variables with the ALIGNED attribute. If you do not 
specify ALIGNED, the compiler issues a warning message and assumes ALIGNED. 
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Character Data 


A character value is a sequence of characters. It can include any language character 
and extralingual character. Any blank included in a character value is included in 
the count of the length of the value. A character value is stored in consecutive 
bytes, each character occupying | byte. 


A character constant is a sequence of characters enclosed in apostrophes. The value 
of a character constant is the string of characters between the enclosing apostrophes, 
except that if you want to represent an apostrophe within the string, you must write 
it in the constant as two consecutive apostrophes with no intervening blanks. A 
character constant has the attribute CHARACTER(n), where n is the length of the 
character value represented by the constant. 


The maximum length of a character constant, including the enclosing apostrophes, 
and counting each apostrophe as a separate character, is 512. 


Examples of character constants and the lengths of their values are: 


Constant Length 
"LOGARITHM TABLE’ (15) 
"PAGE 5! (6) 
'SHAKESPEARE''S ''!''HAMLET'!!'!! (24) 
'SHAKESPEARE''S ''HAMLET'!! (22) 
'AC438-19! (8) 
it (0) 


The last example is the null character constant, which is written as two consecutive 
apostrophes and represents the null character string. 


You declare a character variable with the CHARACTER attribute and a length 
specification. For example: 


DECLARE USER CHARACTER (15); 


In this statement, USER represents character values 15 characters long. 


VARYING Attribute 


The VARYING attribute specifies that the variable is to represent varying-length 
strings. When you specify VARYING, the length of the CHARACTER attribute 
specifies the maximum length. 


The length at any time is the length of the current value. The storage allocated for 
varying-length strings is 2 bytes longer than the declared maximum length. The left- 
most 2 bytes hold the character string’s current length in bytes. 


The following DECLARE statement specifies that the name USER 1s to represent 
varying-length character data items with a maximum length of 15: 


DECLARE USER CHARACTER (15) VARYING; 
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The length for USER at any time is the length of the data item assigned to it at that 
time. You can determine the length at any given time with the LENGTH built-in 
function. 


PICTURE Data Attribute 
Data declared with the PICTURE attribute is known as picture data. A picture 
data item has a numeric value, which is represented as a character value by means of 
the editing characters in the picture specification. 


Only data that is, or can be converted to, an arithmetic value can be assigned to a 
picture variable. 


>>—PICTURE——'picture_specification'——*<« 


Abbreviation: PIC for PICTURE 


picture_specification 
A sequence of picture characters. It specifies the character form and arithmetic 
characteristics of the value of the picture variable. 


There must be at least one blank between the keyword PICTURE and the first 
apostrophe. 


The syntax of the picture specification is as follows: 
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zero-suppression Iv zero-suppression | CR 
| zero-suppression | [9 ne | [Vv : eee fu DB 


zero-suppression |V zero-suppression | | ‘ $ 
| [zero-suppression |[9...][v9.. .] 


f9...jJ[v9...][R] 


[V sign... | 
Sieue (VO: 


drifting-sign 


fem 


drifting-currency [9 Se ‘4 [Vv O33 | beg 


drifting-currency[9...|[V9...] @ [sign | 


where “zero suppression” js Zieh, We 

"sign" is + | - | S 

“drifting-currency” is $$... J 
and "drifting-sign" is Pe ee eee eon: eae 


Figure 12-3. Picture Specification Syntax 


The following should be noted: 
¢ Only one type of sign character may be used. : 
¢ Only one type of zero suppression character may be used. J 
¢ The picture specification must contain at least one digit position. 


¢ Insertion characters (, . / B), which are not shown in the syntax, can appear 
anywhere in a picture specification except within the character pairs CR (credit) 
or DB (debit). 


Picture specifications may contain both uppercase and lowercase characters. The 
maximum length of a picture specification is 255 characters, which includes up to 15 
digit positions, plus an optional V picture character. 


Picture data items having only the characters 9, V, and R in the picture specification 

are represented in storage as zoned decimal numbers. Zoned decimal data is stored 

with the rightmost four bits of each byte holding a decimal digit in binary form. If 

the character R is the rightmost character in the picture specification, the leftmost 
four bits of the nghtmost byte hold the sign indication. Arthmetical operations Za 
using picture data items of this type process more quickly than arithmetical oper- 
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ations using picture data items which include edit characters in the picture specifica- 
tion, because less conversion is required before the operation can be processed. 


Like a coded arithmetic data item, a picture data item has a base, a scale, and a 
precision. The base of a picture data item is decimal, and its scale is fixed-point. 
The precision is derived from the picture specification. It 1s (p,q), where p, the 
number of digits, is the number of digit positions (conditional or unconditional) in 
the picture specification, and q, the scale factor, is the number of digit positions to 
the right of the V picture character; q= 0 if the V picture character is omitted. 


The picture specification in the PICTURE attnbute describes: 


e The range of numeric values, expressed by the digit positions of the picture 
specification, the assumed decimal point, and possibly a sign. 


e The representation as a character value, expressed by all the picture characters 
except the V, which specifies the assumed location of a decimal point. The 
character value is obtained by representing, or editing, the numeric value by 
means of the picture specification: the decimal digits in the character value are 
taken from the numeric value, and the editing characters are inserted as pre- 
scribed by the picture specification. 


For example: 


DECLARE PRICE1 PICTURE '999V99', 
PRICE2 PICTURE '$999V.99'; 


PRICE] can represent numeric values in the range of 000.00 through 999.99; it 
cannot represent negative values. Any value assigned to PRICE] is maintained as a 
zoned decimal value of 5 decimal digits, with an assumed decimal point preceding 
the nghtmost two digits. A value assigned to PRICE] is aligned on the assumed 
decimal point in the same way that decimal point alignment is maintained for fixed- 
point decimal data. 


PRICE2 can represent the same range of numeric values. In the picture specifica- 
tion for PRICE2, the currency symbol ($) and the decimal point (.) are editing char- 
acters. They are stored as characters in the data item. They are not, however, a 
part of its numeric value. 


Picture data is stored in its character form. The use of its numeric value involves a 
conversion to decimal fixed-point. Depending on the context of a picture data item, 
its character value or its numeric value is used. 
The character value is used when: 

¢ The picture variable appears in an assignment to a character variable. 


e A reference is made to a character variable that is based on a pointer to the 
picture variable. 


e The value of a picture variable is transmitted by means of edit-directed output 
with the A format item or by record data transmission. 


The numeric value is used when: 
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¢ Arithmetic operations are processed on the picture variable. 
¢ The picture variable is assigned to an arithmetic variable. 
e The picture variable is used with the B, B1, B4, E, or F format items. 


A value that is assigned to a picture variable will, if necessary, be truncated or 
extended with zeros or other characters (as prescribed by the picture specification) at 
the affected end. If significant digits or a negative sign are truncated, the result is 
undefined. 


For example: 


DECLARE PICPRICE PICTURE '$99V.99'., 
CHARPRICE CHARACTER (6), 
DECPRICE FIXED DECIMAL (6,2); 

PICPRICE = 12.28; 

CHARPRICE = '$12.28'; 


In this example, after processing the second assignment statement, the character 
values of PICPRICE and CHARPRICE are identical. They would be printed in 
exactly the same way if they were printed in stream output by means of the A 
format item. PICPRICE and CHARPRICE produce different results, however, if 
they are used in an arithmetic context. Consider the following assignment 
Statements: 


DECPRICE = PICPRICE; 


The value of DECPRICE is now 0012.28. The numeric value only is assigned: the 
currency symbol and decimal point are ignored, because they are editing symbols 
and not part of the arithmetic value. 


CHARPRICE = PICPRICE; 

The value of CHARPRICE is now '$12.28'. Because the assignment is to a char- 
acter variable, the editing characters are part of the the value assigned. 

DECPRICE = CHARPRICE; 

This assignment statement would cause an error. The value of CHARPRICE is not 
a valid arithmetic constant, because it includes a currency symbol. 

PICPRICE = CHARPRICE; 


This assignment statement would also cause an error. CHARPRICE includes a 
currency symbol, which makes it an invalid arithmetic constant. 


Digit and Decimal Point Characters 
The picture character 9 specifies a digit position; the picture character V specifies the 
assumed decimal point. 


9 Specifies that the associated position in the data item is to contain a digit. 


A string of 9s (picture characters) specifies that the item is to be represented 
by a character value of the same length as the string of 9s, each character of 
which is a digit (0 through 9). The numeric value is the value of the digits as 
an unsigned decimal number. For example: 


DECLARE NUMBER PICTURE '999'; 
NUMBER = 123; 
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In this example, the precision derived from the picture specification 1s (3,0). 
The character value of NUMBER is '123', and its numeric value is 123. 


Vv Specifies that a decimal point is assumed at this position in the associated 
data item. But it does not specify to insert an actual decimal point. The 
integer and fractional parts of the assigned value are aligned on the V char- 
acter; therefore, an assigned value may be truncated or extended with zero 
digits at either end. If no V character appears in the picture specification, a V 
is assumed at its right-hand end. This will truncate the assigned value to an 
integer. For example: 

DECLARE VALUE PICTURE '99V999', 
CVALUE CHARACTER(5) ; 


VALUE = 12.345; 
CVALUE = VALUE; 


In this example, the derived precision of VALUE is (5,3), its character value 
is '12345', and its numeric value is 12.345. On assignment to CVALUE, the 
character value is assigned. The resulting value of CVALUE is '12345'. 


The statements 
VALUE = 1.2; 
CVALUE = VALUE; 


result in the character value of VALUE being '01200' and its numeric value 
being 1.2. The resulting value of CVALUE is '01200'. To assign -0.1 or 
123.4 to VALUE would, however, give an undefined result. 


Figure 12-4 on page 12-27 gives examples of digit and decimal point picture specifi- 
cations. 


Zero Suppression Characters 
The zero suppression picture characters specify conditional digit positions in the 
character value and replaces leading zeros with asterisks or blanks. 


Z Replaces a leading zero in the associated data position with a blank character. 
* Is used in the same way as the picture character Z, except that leading zeros 


are replaced by asterisks. 


Figure 12-5 on page 12-27 gives examples of the use of zero suppression characters. 


Insertion Characters 
The insertion picture characters (, . / B) inserts the specified character (comma, 
period, slash, or blank) into the associated character value position of the picture 
data, if there is no zero suppression. They do not indicate digit positions, but are 
inserted between digits. Insertion characters are applicable only to the character 
value. They specify nothing about the numeric value of the data item. 


If zero suppression occurs, the character is inserted only in the following cases: 


e When an unsuppressed digit appears to the left of the insertion character 
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° When a V appears immediately to the left of the insertion character and the 
fractional part contains a significant digit. 


¢ When the insertion character is at the start of the picture specification or is pre- 
ceded only by characters that do not specify digit positions. 


In all other cases where zero suppression occurs, an insertion character is treated as 
though it were a zero suppression character. 


The following example shows decimal conventions that are used in various 
countries: 


DECLARE A PICTURE 'Z,ZZZ,ZZZV.99', 
B PICTURE. Sf. e*", = 99". 
C PICTURE: “*B***B***) 907s 


The derived precision of the picture variables A, B, and C is (9,2). 


If A, B, and C are assigned the integer constant 1234, the character value of A, B, 
and C, respectively, will be 


' 1,234.00! 
He] 234,00! 
ieee] 234,00! 


Their numeric value is 1234. 


The following example shows that the decimal point is aligned on the character V 
and not on the period insertion character: 


DECLARE RATE PICTURE '9V99.99'; 
RATE = 7.62; 


The derived precision of RATE is (5,4), its character value is '762.00', and its 
numeric value is 7.62. 


Figure 12-6 on page 12-28 gives examples of the use of insertion characters. 


Sign and Currency Characters 
The sign and currency picture characters are §, S, +, and -. A fuller description of 
these characters is given below. 


You can use these picture characters as either static or drifting characters. 


The static use specifies that a sign, a currency symbol, or a blank appears in the 
associated position. A static character is specified by its single occurrence in the 
picture specification. 


The drifting use specifies to suppress leading zeroes. A drifting character is specified 
by multiple use of that character in a picture specification. The position associated 

with the leftmost drifting character can contain only the drifting character or blank, 

never a digit. Therefore, if the drifting string contains the drifting character 7 times, 
the string is associated with 7-1 conditional digit positions. After a data assignment 
to a picture variable, the rightmost suppressed position associated with the picture 
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character will contain a sign, a blank, or a currency symbol (except that where all 
digit positions are occupied by drifting characters and the value of the data item 1s 
zero, the drifting character is not inserted). For example: 


DECLARE A PICTURE 'SSSV.9'; 
A = -2.0; 


In this example, the derived precision of A is (3,1), its character value is ' -2.0', and 
its numeric value is -2.0. 


Any insertion character within or immediately following the string is considered part 
of the drifting string. A V ends the drifting string, except when the numeric value of 
the data item is zero; in that case, the character value will be all blanks (except for 
any insertion characters to the left of the drifting string). 


In the data item, the character value position associated with an insertion character 
in a string of drifting characters contains one of the following: 
¢ The insertion character, if there is a significant digit to the left 


e The drifting character, if the next position to the night contains the leftmost sig- 
nificant digit of the value 


e Blank, if the leftmost significant digit of the value is more than one position to 
the right. 
The sign and currency characters are as follows: 


$ Specifies the currency symbol. For example: 
DECLARE PRICE PICTURE '$99V.99'; 
PRICE=12.45; 


The derived precision of PRICE is (4,2), its character value is '$12.45', and 
its numeric value 1s 12.45. 


S Specifies the plus sign character (+) if the numeric value is greater than or 
equal to zero; otherwise it specifies the minus sign character (-). For 
example: 


DECLARE ROOT PICTURE 'S999'; 
50 is held as '+050', zero as '+000', and -50 as '-050'. 


+ Specifies the plus sign character (+ ) if the numeric value is greater than or 
equal to zero; otherwise it specifies a blank. 


- Specifies the minus sign character (-) if the numeric value is less than zero; 
otherwise it specifies a blank. 


If, in an assignment to a picture variable, the fractional digits are truncated so that 
the resulting numeric value 1s zero, the sign inserted in the data item corresponds to 
the value of the data item prior to its truncation. Therefore, the sign in the picture 
data may depend on how the value was calculated. 


Figure 12-7 on page 12-29 gives examples of the use of drifting picture characters. 
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Credit and Debit Characters 
The character pairs CR (credit) and DB (debit) specify the signs of picture data. 


CR = Specifies that the associated positions will contain the letters CR if the 


numeric value is less than zero; otherwise, the positions will contain two 
blanks. 


DB Is used in the same way as CR, except that the letters DB appear in the asso- 
ciated positions. 


Figure 12-8 on page 12-30 gives examples of the CR and DB picture characters. 


Digit and Signed Character 
The digit and signed character R specifies that the associated position will contain 
an EBCDIc character or a digit, depending on the sign of the data item. 


e Ifthe arithmetic value of the data item is less than zero, the associated position 
contains an EBCDIC character. This EBCDIC character represents the negative 
value of the corresponding digit shown in the table below. 


¢ Ifthe arithmetic value of the data item is greater than or equal to zero, the asso- 
ciated position contains a digit. 


The associated characters and digits are shown in the following table: 


For example: 


DECLARE INTEGER PICTURE '99R'; 
READ FILE (INFILE) INTO (INTEGER); 


will set INTEGER to 321 if '321' 1s found in the next record and will set 
INTEGER to -321 if '32J' 1s found. 


12-26 PL/I User's Guide and Reference 


PROBLEM DATA ATTRIBUTES 


Source Picture Derived Character Numeric 
Data Specification Precision Value Value 


99999 


99999 


999V99 


99999 


Figure 12-4. Digit and Decimal Point Examples 


Data Specification Precision Value Value 
ZZZ99 
ZLL9I9 
LZLLZZLZZ 
ZLZLZL 
ZZZ99 
ZZLN99 
ZLZNZZ, 


LZLLZVNLZZL 


Tre T 


AHO Ok #KO] 


$**9.99 $**0.95 


$**9.99 $123.50 


Figure 12-5. Examples of Zero Suppression 


Note: In this figure, the letter b indicates a blank character. 
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Source Picture Derived Character 
Data Specification Precision Value 


1234 9,999 1,234 


Numeric 
Value 


1234 


1234.56 9,999V.99 1,234.56 


1234.56 


12.34 ZZ.VNZZ 


12.34 


12.34 


0.03 


LZZ.NZZ 


bbb03 


LLV LL bb.03 


ZZNV ZZ 12.34 


ZLZNV .ZZ bbbbb 


1234567.89 9,999,999V .99 1 234,567.89 1234567.89 


12345.67 ** 999V.99 12,345.67 12345.67 


123.45 *#* 123.45 123.45 


** 999V.99 


1234567.89 9.999.999V ,99 1.234.567,89 1234567.89 


123456 99/99/99 


123456 


123456 99.9/99.9 12.3/45.6 123456 


1234 ZZ/LZ/ZZ bbb 12/34 1234 


ZZ/ZZ/ZZ bbbbbb12 


ZL/LL/LZZ bbbbbbbb 


il ala es FORO bob ok 


ok kkk kodak 


eB eB eH 


123456 99B99B99 12b34b56 123456 


123 9BB9IBBI I bb2bb3 123 


12 9BB/9BB lbb/2bb 12 


Figure 12-6. Examples of Insertion Characters 


Note: In this figure, the letter b indicates a blank character. 
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Source Picture Derived Character Numeric 
Data Specification Precision Value Value 


$999V.99 $123.45 


| 99$ | 125 


$ZZZV.99 $bb 1.23 
$ZZZV.ZZ bbbbbbb 
$$$.$$ bbbbbb 
$$$9V.99 $123.45 
$$$9V.99 | bb$1.23 
$$$,999 bbb$012 
$$$,999 b$1,234 
SZZZV.99 +bb2.45 
58,5589 bb+214 
SS,SS9 bbbb-4 
-999V.99 - 123.45 
999V.998 123.45+ 
++B+9V.99 bbb+ 1.23 


---9V.99 bbb 1.23 


SSS9V.99 bb-1.23 


Figure 12-7. Examples of Signs and Currency Symbols 


Note: In this figure, the letter b indicates a blank character. 
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Source Picture Derived Character Numeric 
Data Specification Precision Value Value 


$Z.99CR : $1.23CR 


$ZZV.99CR $12.34bb 
$ZZV.99DB $12.34DB 


$ZZV.99DB $12.34bb 


Figure 12-8. Examples of CR and DB Picture Characters 


Note: In this figure, the letter b indicates a blank character. 


Program Control Data Attributes 


Program control data attributes refer to pointer, label, entry, and file data. Scope 
and storage attributes can be specified for program control data. 


POINTER Attribute 


»>—— POINTER» 


Abbreviation: PTR for POINTER 


A pointer value identifies the location of data in storage. You declare a pointer vari- 
able with the POINTER attribute. You can also specify VARIABLE, scope or 
storage attributes, with the default values shown in Figure 12-1 on page 12-3. 
Pointer variables can be grouped into aggregates. 


A pointer value may be obtained by one of the following means: 


¢ The ADDR or NULL built-in function. 
¢ A READ statement with the SET option. 
¢ The ALLOCATE statement. 


A pointer value can also be obtained by means of a parameter from some built-in 
subroutines. 


Pointer values can be assigned, compared (= or — =), passed as arguments, or 
returned by a function. They cannot be converted or specified in operations. 


If you use a pointer as the target of an assignment statement, the source must be 
either another valid pointer, or the ADDR or NULL built-in function. 


You can use a pointer, together with a based variable, to access the location in 


storage identified by the pointer value (see “Based Variable Reference and Pointer 
Qualification” on page 5-20). 
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Pointer Built-In Functions 


The ADDR built-in function, when applied to a variable, returns a pointer value 
that identifies the location of the variable in storage. 


The NULL built-in function returns a null pointer value, which does not identify 
the location of any variable. You use this value when a pointer variable should not 
identify a location in storage. A pointer variable acquires the null pointer value by 
assignment of the value of the NULL built-in function. 


A label identifies a statement in the running program. There are two kinds of labels: 
label constants and label variables. 


A label constant is a name written as the label prefix of any statement other than 
PROCEDURE. During processing, program control can be transferred to the state- 
ment by referring to its label prefix. 


A name is explicitly declared as a label constant by its appearance as a label. 
In the example: 


ABCDE: MILES = SPEED * HOURS; 


ABCDE is a label constant. The statement can be processed either by normal 
sequential processing of instructions or by transferring control to it from some other 
point in the program by means of a GO TO statement. 


You declare a label variable by specifying the LABEL attribute. 


>>——LABEL—_>« 


When you use the LABEL attribute, you can also specify VARIABLE, scope, and 
storage attributes (although INITIAL is not valid). Defaults are shown in 

Figure 12-1 on page 12-3. Label values can also be grouped into aggregates. You 
set a label variable by assignment. 


You can use a label variable with the GO TO statement. Control is transferred to 
the statement identified by the value of the label variable. For example: 


DECLARE LABEL1 LABEL VARIABLE; 
STMT1: ITEM1 = ITEM2; 


STMT2: ITEM1 = ITEM3; 


LABEL1 = STMT1; 
GO TO LABEL1; 
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STMT 1 and STMT2 are label constants, and LABEL] 1s a label variable. After 
STMT1 has been assigned to LABELI, the statement GO TO LABELI transfers 
control to the statement labeled STMT1. Elsewhere, the program could contain a 
statement LABEL] = STMT2. Any reference to LABEL1 would then be the 
same as a reference to STMT2. This value of LABEL] is retained until another 
value is assigned; but it becomes invalid if the block containing the statement 
labeled STMT2 becomes inactive. 


You use the ENTRY attribute to declare an entry variable or an external entry con- 
stant and to describe the attributes of any parameters the associated entry value may 
have. 


An entry data item represents a procedure. You refer to an entry data item by 
means of an entry reference. 


An entry reference is an entry constant, an entry variable reference, or a function 
reference that returns an entry value. 


An entry constant is the label prefix to a PROCEDURE statement. If the proce- 
dure is external, you must declare the entry constant with the ENTRY attribute. If 
the procedure is a function, you must declare the entry constant with the 
RETURNS attnbute. 


An entry variable is a variable to which an entry value can be assigned. It is 
declared with the ENTRY and VARIABLE attributes and, for a function, with the 
RETURNS attribute as well. You cannot declare an internal entry constant in a 
DECLARE statement. You can also specify scope and storage attributes (except 
INITIAL). Defaults for these are shown in Figure 12-1 on page 12-3. Entry vari- 
ables can be grouped into aggregates. 


When an entry constant which is an entry point of an internal procedure is assigned 
to an entry variable, the assigned value remains valid only for as long as the block 


that the entry constant was internal to remains active. 


The syntax of the ENTRY attribute is as follows: 
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vow ee 
(parameter_descriptor_list) 


where 'parameter_descriptor_list' is: 


[ i“ 


nonstructure_parameter_descripto 


structure_parameter_descriptor 


*. 


‘nonstructure_parameter_descriptor' is: 


ee. 2 ee 


'structure_parameter_descriptor' is: 


attribute 
and ‘level' is: 


»——-——jnteger_constant-——> 


parameter_descriptor_list 
A list of parameter_descriptors, each of which gives a set of attributes for the 
parameter it corresponds to positionally in the procedure. 
Parameter_descriptors are separated by commas. 


The number of parameter_descriptors in the ENTRY attnbute and the attri- 
butes specified for each parameter must match the parameters as declared in the 
procedure represented by the entry name. An ENTRY attnbute without a 
parameter descriptor_list describes a procedure with no parameters. 


nonstructure_parameter_descriptor 
For a nonstructure_parameter_descriptor, you must specify at least one data 
attribute other than FILE. This corresponds to the rules for giving attributes to 
a parameter in a DECLARE statement (see ‘Parameter Attnbutes” on 
page 14-3). The attributes are separated by blanks. If you specify the ENTRY 
attribute as a parameter_descriptor, it must not have a parameter_descriptor or a 
RETURNS attribute. 


structure_parameter_descriptor 
Each level number, together with any attributes specified for it, 1s separated 
from the next by acomma. You can specify the same attributes for a field 
name as you can for a nonstructure_parameter_descriptor. 


The level numbers need not be the same as those of their corresponding param- 
eters, but they must be in the same order with identical structuring. 
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| IBM Extension | 


* 


This parameter_descriptor is valid only when the entry variable or entry con- 
stant represents a non-PL/I routine, that is, one for which you have coded 
OPTIONS (ASSEMBLER). It specifies that no check is made against this 
parameter of the associated non-PL/I routine. 


fe End of IBM Extension ee 


The rules for specifying string lengths or array bounds in a parameter_descriptor are 
the same as for parameter lengths and bounds in a DECLARE statement. 


For arrays, the parameter_descriptor must include the array dimensions in paren- 
theses as the first attribute. For example, if the PL/I program PROC1 had parame- 
ters coded as follows: 


PROC1: PROCEDURE (EMPLOYEE,COMMISSIONS, NAME) ; 


DECLARE EMPLOYEE FIXED DECIMAL (5), 
COMMISSIONS(20) FIXED DECIMAL (7), 
NAME CHARACTER (*); 


the ENTRY declaration would be as follows: 


DECLARE PROC1 ENTRY (FIXED DECIMAL (5), 
(20) FIXED DECIMAL (7), 
CHARACTER (*)); 


The following example illustrates the use of structure_parameter_descriptors in an 
external procedure: 


TEST: PROCEDURE 
(AFID,BFIB,CSTRUC,DSTRUC ,ECHAR,P) ; 
DECLARE AFID FIXED DECIMAL(5), 

BFIB FLOAT BINARY (15), 
1 CSTRUC, 
5 QCHAR CHARACTER (3), 
5 RSTRUC, 
10 SFID FIXED DECIMAL (5), 
1 DSTRUC, 
5 XCHAR CHARACTER (3), 
5 YSTRUC, 
10 ZFID FIXED DECIMAL (5), 
ECHAR(*) CHARACTER (10), 
P POINTER; 


END TEST; 
To call this procedure, these structure_parameter_descriptors could be declared as 
follows: 
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DECLARE TEST ENTRY 
(DECIMAL FIXED (5), 
BINARY FLOAT (15), 


3 
5 CHARACTER (3), 
oF 
10 DECIMAL FIXED (5), 
1, 
5 CHARACTER (3), 
oF 

10 FIXED DECIMAL (5), 
(*) CHARACTER (10), 
POINTER) ; 


The use of the parameter_descriptor * is illustrated in the following example: 


DECLARE TRANSFER ENTRY 
(CHARACTER(10),*,*,FIXED DECIMAL(5)) 
OPTIONS (ASSEMBLER) ; 


The declaration indicates four parameters of a non-PL/I routine, with attributes spec- 
ified for the first and fourth parameter. 


No parameter_descriptor_list can be defined for an ENTRY attribute specified in a 
parameter_descriptor_list for an ENTRY variable. For example, the following dec- 
laration is not valid: 


DECLARE SUBPROC ENTRY (FIXED BINARY (15), 
FLOAT DECIMAL (7), 
ENTRY (CHARACTER (10)) ); 


The parameter_descriptor_lst for the ENTRY attnbute would have to be specified 
in SUBPROC: 


SUBPROC: PROCEDURE (BINARYITEM, DECIMALITEM,ENTRYITEM) ; 


DECLARE ENTRYITEM ENTRY (CHARACTER(10)); 


RETURNS Attribute 


You specify the RETURNS attribute in a DECLARE statement for an entry vari- 
able or external entry name that represents a function. It specifies the attributes of 
the returned value. 


>>—RETURNS (—at tri var —>< 


attribute 
The valid attributes are the same as those for the RETURNS option (see 
“PROCEDURE Statement” on page 14-2). 
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The attributes specified in the RETURNS attribute for an entry variable or an 
external entry constant must agree with those specified in the RETURNS option of 
the corresponding PROCEDURE statement. 


OPTIONS(ASSEMBLER) Attribute 


The OPTIONS(ASSEMBLER) attribute allows you to communicate with a 
non-PL/I program. 


>>——OPTIONS (ASSEMBLER) —* 


Abbreviation: ASM for ASSEMBLER 


ASSEMBLER 
Specifies that the designated entry point is a program written in an AS/400 lan- 
guage other than PL/I. PL/I will pass arguments directly to the program, rather 
than through PL/I contro] blocks. Entries with the ASSEMBLER option are 
subject to the following rules: 


e They cannot be used as a function reference. 


e Any number of arguments can be passed in the CALL statement calling the 
entry, from zero up to the number specified by the entry declaration, but 
intervening arguments cannot be omitted. 


BUILTIN Attribute 


The BUILTIN attribute specifies that the declared name denotes a built-in function, 
a pseudovariable, or a built-in subroutine. 


>>——BUILTIN—>< 


You only need to use the BUILTIN attribute when you are using the name of a 
built-in function or subroutine (see Chapter 15, “Built-In Functions, Subroutines, 
and Pseudovariables’’) as a user-defined name in a different block. 


When you use a built-in name as a user-defined name, you declare it again with the 
BUILTIN attribute in any other block to associate it again with the built-in func- 
tion or built-in subroutine. Consider the following examples: 
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Example I: 


A: PROCEDURE; 
DECLARE (SQRT(20),P) FLOAT BINARY (20); 


X = SORT(P); 


B: BEGIN; 
DECLARE SQRT BUILTIN; 
Z = SQRT(P); 
END B; 


END A; 
Example 2: 


A: PROCEDURE; 
DECLARE P FIXED DECIMAL (7,2); 
SQRT: PROC(PARAM) RETURNS (FIXED(7,2)); 
DECLARE PARAM FIXED (13); 


END SORT; 
x : SQRT(Y) 


B: BEGIN; 
DECLARE SQRT BUILTIN; 
Z = SQRT(P); 
END B; 


END A; 


In A of both examples, SQRT 1s a user-defined name. In the assignment to the 
variable X, SQRT is a reference to the user-defined name SQRT. In B of both 
examples, SQRT is declared with the BUILTIN attribute. Any reference in B to 
SQRT is recognized as a reference to the built-in function and not to the user- 
defined name SQRT declared in A. For information on using built-in functions, 
subroutines, and pseudovariables, see Chapter 15, ‘Built-In Functions, Subrou- 
tines, and Pseudovariables.” 


VARIABLE Attribute 


You can use the VARIABLE attribute to declare a variable of any type except 
FILE. 


>>——-VARIABLE—>< 


VARIABLE is implied for parameters, structures, and structure members, by any 
scope, storage class, or alignment attribute, and by some of the data type attributes 
(the default rules are given in ‘‘Names” on page 4-12). Constant is implied for label 
prefixes, and by ENTRY, unless VARIABLE is implied by other attributes. You 
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must use the VARIABLE attribute to declare an entry variable if VARIABLE 1s 
not implied by any other attribute. 


Aggregate Data Declarations 


All data types, except file or entry constants, can be grouped into aggregates. The 
types of aggregates are arrays and structures. Single data items, called scalars, can be 
grouped into arrays or structures. Single variables, called scalar variables, can be 
grouped into array variables or structure variables. 


An array is a collection, into one or more dimensions, of one or more array- 
elements with identical attributes. An array-element can be a scalar variable or a 
structure. Only the array itself is given a name. An individual item of an array is 
referred to by giving its subscript. 


An array is declared with the dimension attribute. 


A structure is a collection of data items that need not have identical attributes. Like 
an array, the entire structure is given a name, which can be used to refer to the 
entire aggregate of data. But, unlike an array, each field of a structure also has a 
name. 


You use level numbers to specify the organization of a structure in a DECLARE 
statement. 


Arrays and the Dimension Attribute 
The dimension attribute specifies the number of dimensions of an array and indi- 
cates the bounds of each dimension. It must immediately follow the array name or 
factored list of array names. 


p>— ( sities 


where ‘bounds' are: 


upper_bound 


lower_bound: 


te 


and where 'lower_bound' is 1 and ‘upper_bound' is: 


constant 
scalar_variable 


bounds 
The upper_bound or upper and lower_bounds. The number of bounds specifi- 
cations indicates the number of dimensions in the array. For a parameter, you 
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can specify an asterisk to indicate that the lower and upper_bound are taken 
from the associated argument in the calling procedure. 


lower_bound 
The beginning of the dimension. If you specify the lower_bound, it must be an 
optionally signed integer constant whose value is 1. If you omit the 
lower_bound, 1 is assumed by default. 


upper_bound 
The end of the dimension. The upper_bound must be less than or equal to 
32 767. You can specify the upper_bound as follows: 


e If the variable is static, based, a member of a structure, or a parameter, the 
upper_bound must be an optionally signed integer constant. 


e If the variable is automatic, the upper_bound must be an optionally signed 
integer constant or an unsubscripted non-based integer variable reference. 


¢ The value of the upper_bound must be greater than or equal to 1. 


The extent of a dimension is the number of integers between the lower and 
upper_bounds, including the bounds. 


The maximum number of dimensions is 15. The total length of an array must not 
exceed 4194304 bytes (4 megabytes). 


For a discussion and examples of how to use the dimension attribute to declare 
arrays, see “Using Arrays and the Dimension Attribute” on page 5-1. 


Structures and Level Numbers 
You can specify the organization of a structure in a DECLARE statement by pre- 
ceding the names with level numbers. The major structure name must be declared 
with the level number 1, and minor structures and field names with level numbers 
greater than 1. Level numbers must be integer constants. 


The level numbers you choose for successively deeper levels need not be the imme- 
diately succeeding integers. A minor structure at level n contains all the names with 
level numbers greater than n that lie between that minor structure name and the 
next name with a level number less than or equal to n. 


The description of a major structure is ended by the declaration of another item 
with the level number |, by the declaration of another item with no level number, 
or by the end of the DECLARE statement or descriptor list. 


The maximum depth of logical levels is 15, and the highest valid level number is 
255. The maximum length of a structure is 32 767 bytes. 


For a discussion of how to use level numbers to describe structures, see “Using 
Arrays and the Dimension Attribute” on page 5-1. 


A structure name, either major or minor, can be given a dimension attribute in a 


DECLARE statement to declare an array of structures. An array of structures is an 
array whose elements are structures that have identical names, levels, and element 
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attributes. For a discussion of how to use arrays of structures, see “Arrays of 
Structures” on page 5-5. 


Alignment Attributes 


By means of the ALIGNED and UNALIGNED attributes, you can choose to align 
data on the appropriate boundary. You can specify alignment attributes for scalars 
and arrays only. 


Ty 
UNALIGNE 


Abbreviation: UNAL for UNALIGNED 


ALIGNED 
Specifies that the data item is aligned on the storage boundary corresponding to 
its data type requirement. For example, BIN (15) data is aligned on a halfword 
boundary and BIN (31) data on a fullword boundary. See “Data Mapping” on 
page 5-9 for a definition of these requirements. 


| Full Language Extension | 


UNALIGNED 
Specifies that the data need not be aligned. Although the UNALIGNED attn- 
bute can reduce storage requirements, it may increase run time. 


ee End of Full Language Extension ee 
Bit data must be declared as ALIGNED. 

The default for character data and picture data is UNALIGNED. UNALIGNED 
can also be specified for fixed-point binary, floating-point binary, and floating-point 


decimal data. 


For all other data types, the default is ALIGNED. ALIGNED can also be specified 


for character varying data. 


For a discussion of how to use the alignment attributes, see ‘Data Alignment and 
the Alignment Attributes” on page 5-7. 


Scope Attributes 


You can use the INTERNAL and EXTERNAL attributes to specify the scope of a 
name. 
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i pecs 
EXTERNAL 


Abbreviation: INT for INTERNAL 
EXT for EXTERNAL 


INTERNAL 
The default for variables with any storage class and for members of structures. 
Entry names of internal procedures are always internal. 


EXTERNAL 
The default for file and entry constants. Entry names of external procedures are 
always external. 


For structures, INTERNAL and EXTERNAL should be specified in level 1 decla- 
rations only. An error message is sent if a member of a structure has a scope speci- 
fied that is different from the scope specified in the level 1 declaration. 


Storage Attributes 


The declaration of a variable includes a storage class attribute either by explicit spec- 
ification or by default. 


The way storage is allocated for a variable, and the degree of control you can exer- 
cise Over storage, are determined by the storage class of that variable. There are 
three storage classes: static, automatic, and based. Each is specified by its corre- 
sponding storage class attribute. 


You can specify the storage class for level-one variables only. Elements of arrays 
and members of structures inherit the storage class of the array or structure. 


You cannot specify a storage class for a parameter or a named constant. 


The default is AUTOMATIC for internal vanables and STATIC for external vari- 
ables. 


Automatic and based variables can have internal scope only. Static variables can 
have either internal or external scope. 


AUTOMATIC Attribute 
You declare an automatic variable with the AUTOMATIC attribute. 


>>—— AUTOMAT 1C-—>« 


Abbreviation: AUTO for AUTOMATIC 


Automatic variables can have internal scope only. 


Chapter 12. Declaring Names and Attributes of Variables 12-41 


STORAGE ATTRIBUTES 


BASED Attribute 


STATIC Attribute 


INITIAL Attribute 


AUTOMATIC is the default for internal variables. 


For a discussion of the use of the AUTOMATIC attribute, see “Using the AUTO- 
MATIC Attribute” on page 5-18. 


You declare a based variable with the BASED attribute. 


iad re ae 
(pointer_variable) 


pointer-variable 
A simple non-based variable with the POINTER attribute. 


Based variables can have internal scope only. 


For a discussion of the use of the BASED attribute, see “Using the BASED 
Attribute” on page 5-19. 


You declare a static variable with the STATIC attribute. 


>>——STATIC-—> 


Any expressions that specify lengths or bounds for a static variable must be integer 
constants. 


Static variables can have either internal or external scope. 
STATIC is the default for external variables. 


For a discussion of the STATIC attribute, see “Using the STATIC Attribute” on 
page 5-16. 


The INITIAL attribute, used with the STATIC attribute, specifies values assigned 
to a scalar or array variable when storage is allocated to it. 
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acdalaunsd Emel denis 


where ‘item' is: 


cae ae a 
initial_element 


(iteration_factor) 


and where ‘initial_element' is: 
simple_string_constant 


arithmetic_constant 


Abbreviation: INIT for INITIAL 


iteration_factor 
An integer constant in the range 1 through 32 767. 


simple_string_constant 
Must be in parentheses when preceded by an iteration factor. 


Any variable declared with the INITIAL attribute may only be of type arithmetic, 
string, PICTURE, or POINTER. 


You can specify the INITIAL attribute for arrays that do not have inherited dimen- 
sions, as well as for scalar variables. In a structure declaration, you can specify the 
INITIAL attribute only for field names. 


You can specify only one initial value for a scalar variable, but more than one for 
an array variable. A structure variable requires separate initialization of each of its 


field names if they are scalar or array variables. 


For a discussion of the use of the INITIAL attribute, see “Using the INITIAL 
Attribute” on page 5-17. 


Chapter 12. Declaring Names and Attributes of Variables 12-43 


STORAGE ATTRIBUTES 


12-44 PL/I User’s Guide and Reference 


ASSIGNMENT 


. Chapter 13. General PL/I Statements 


This chapter describes the statements listed below: 
Assignment 


IF 
ITERATE 
LEAVE 
Null 
OTHERWISE 
| SELECT 

C STOP 

WHEN 


Assignment Statement 


The assignment statement evaluates an expression and assigns its result to a target 
variable, which can be a scalar, array, or structure variable or a pseudovariable. 


( You can assign problem data of any type to a problem data variable or 
pseudovariable. All valid conversions are described in “Data Conversion” on 
page 5-27. 


You can assign program control data only to a program control variable of the same 
data type. 


>>—reference = ee 
BY NAME 


A reference is described in Figure 9-1 on page 9-2. 


A scalar assignment is processed as follows: 
1. Subscripts and pointer qualifications on the left-hand side are evaluated. 
2. The expression on the right-hand side is evaluated. 


3. The value of the expression is converted, if necessary, to the attributes of the 
variable on the left-hand side according to the rules for data conversion. The 
converted value is then assigned to the variable on the left-hand side (see “Data 
Assignment” on page 5-24). 


An aggregate assignment is processed if the left-hand side is an array or structure 
( variable. Only the following cases are valid: 
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e The left-hand side is an array that is not an array of structures and the right- 
hand side is a scalar expression. 


The night-hand side value will be assigned to each array element. 


e The right-hand side is an aggregate variable whose size, shape, and component 
data types are identical to those of the left-hand side variable. 


All scalar data of the nght-hand side variable will be assigned to the corre- 
sponding elements or fields of the left-hand side variable. Because the compo- 
nent data types are identical, no data conversions will occur. 


e The left-hand side is a structure and the right-hand side is a scalar variable. 


The scalar variable is assigned to each member of the structure, with conver- 
sions processed where necessary. If an array is a structure member, the scalar 
variable is assigned to each element of the array. 


Examples of Assignment Statements 
The examples in this section use the following declarations: 


DECLARE INDEX1 BINARY; 
DECLARE (ARRAY1,ARRAY2) (10) BINARY, 
ARRAY3(2, 3,4) BINARY; 

DECLARE 1 STRUCTURE1(5), 
5 BINFIXED1 BINARY, 
5 BINFLOAT1 FLOAT, 

1 STRUCTURE2(5) , 
5 BINFIXED1 BINARY, 
5 BINFLOAT2 FLOAT; 


An example of a scalar assignment 1s: 
ARRAY3(INDEX1,1,2) = ARRAY2(INDEX1) + INDEX1; 


The right-hand side is an operational expression, and the left-hand side is a scalar 
variable. 


The following are examples of aggregate assignments: 


An example of a scalar to array assignment is: 
ARRAY3 = 0; 


An example of a structure to structure assignment is: 
STRUCTURE1(INDEX1) = STRUCTURE2(INDEX1+1) ; 


An example of an array to array assignment is: 
ARRAY1 = ARRAY2; 


An example of an array of structures to array of structures assignment is: 
STRUCTURE] = STRUCTURE2; 
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BY NAME ASSIGNMENT 


In a BY NAME assignment, each target must be a structure or an array of struc- 
tures. A member of a target structure derives its value from those structure 
members in the expression that have the same name. Only those members of a 
target for which a member with the same name exists in the other target are affected. 
For example: 


DECLARE 1 ORDERLIST, 

5 ITEMNAME CHARACTER (36), 

5 ITEMNUMBER CHARACTER (5), 

5 SUPPLIER CHARACTER (15), 

5 PRICE FIXED DECIMAL (5,2), 

1 INVENTORY, 

5 ITEMNAME CHARACTER (36), 

5 ITEMNUMBER CHARACTER (5), 

5 QUANTITY | FIXED DECIMAL (4), 

5 LOCATION CHARACTER (15); 
ORDERLIST = INVENTORY, BY NAME; 


The only two members the two structures have in common are ITEMNAME and 
ITEMNUMBER. Therefore, the effect of the BY NAME assignment 1s: 


ORDERLIST, ITEMNAME = INVENTORY, ITEMNAME; 
ORDERLIST, ITEMNUMBER = INVENTORY, ITEMNUMBER; 


Just as in an ordinary assignment, the expression on the right is fully evaluated 
before any part of it is assigned. 


For a BY NAME assignment involving scalars or arrays, the scalar or array enters 
into all of the implied assignments. For a BY NAME assignment involving nested 
structures, the name selection rules are applied recursively. 


The rules for BY NAME assignment can be stated more precisely. A BY NAME 
assignment is carried out in four steps: 


1. A by-name-parts-list is generated. The by-name-parts-list enumerates those 
structure elements that participate in the assignment. 


2. The by-name-parts-list is used to select from and reorder the members of both 
structures involved in the assignment. 


3. The expression is evaluated, using just those parts selected. Those parts whose 
names correspond are combined. 


4, The value of the expression is transferred to the target, with named parts of the 
value going to the corresponding named parts of the target. 


The by-name-parts-list is generated by first considering both variables that appear in 
the assignment. For each variable that is a structure or an array of structures, list 
the fully-qualified names of the structure members at every level, omitting the vari- 
able name from each fully-qualified name. (Scalars or arrays of scalars do not 
count.) The by-name-parts-list consists of just those names that are common to 
both of the lists from the individual variables. 
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The assignment is interpreted by deleting all members of structures that do not 
appear in the by-name-parts-list, and reordering the reduced structures so that their 
members appear in order of the by-name-parts-list. The assignment is then carried 
out using these new structures. 


For example: 
DECLARE 1 CURRENTPRICE, 


5 REGIONI FIXED DECIMAL (5,2), 

5 REGION2 FIXED DECIMAL (5,2), 
1 NEWPRICE, 

5 REGION2 PICTURE '999V99', 

5 REGION1 PICTURE '999V99'; 


CURRENTPRICE = NEWPRICE; 


In the assignment statement, NEWPRICE.REGION2 is assigned to 
CURRENTPRICE.REGION1 and NEWPRICE.REGION|1 is assigned to 
CURRENTPRICE.REGION2. If the assignment statement had been 


CURRENTPRICE = NEWPRICE, BY NAME; 


NEWPRICE.REGIONI1 would have been assigned to 
CURRENTPRICE.REGION]1 and NEWPRICE.REGION2 would have been 
assigned to CURRENTPRICE.REGIONZ2. 


The following example illustrates structure assignment using the BY NAME option: 


DECLARE 1 BRANDI, 
5 PRODUCTI, 
10 RED FIXED DECIMAL (5), 
10 ORANGE FIXED DECIMAL (5), 
5 PRODUCT2, 
10 YELLOW FIXED DECIMAL (5), 
10 BLUE FIXED DECIMAL (5), 
10 GREEN FIXED DECIMAL (5); 
DECLARE 1 BRAND2, 
5 PRODUCTI, 
10 BLUE FIXED DECIMAL (5), 
10 GREEN FIXED DECIMAL (5), 
10 RED FIXED DECIMAL (5), 
5 PRODUCT2, 
10 BROWN FIXED DECIMAL (5), 
10 YELLOW FIXED DECIMAL (5); 


The lists used to compose the by-name-parts-list are: 
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DO 


BRAND1: 

PRODUCT 1: 
PRODUCT1. RED 
PRODUCT 1. ORANGE 

PRODUCT2: 
PRODUCT2. YELLOW 
PRODUCT2. BLUE 
PRODUCT2. GREEN 


BRAND2: 

PRODUCT 1: 
PRODUCT1.BLUE 
PRODUCT 1.GREEN 
PRODUCT1.RED 

PRODUCT2: 
PRODUCT2. BROWN 
PRODUCT2. YELLOW 


If we code the assignment statement 
BRAND1 = BRAND2, BY NAME; 


the by-name-parts-list for the assignment is 


PRODUCT1: 
PRODUCT1.RED 

PRODUCT2: 
PRODUCT2. YELLOW 


The assignment statement would therefore be the same as the following: 


BRAND1.PRODUCT1.RED = BRAND2.PRODUCT1. RED; 
BRAND1.PRODUCT2. YELLOW = BRAND2.PRODUCT2. YELLOW; 


If we code the assignment statement 
BRAND1.PRODUCT1 = BRAND2.PRODUCT1, BY NAME; 


the by-names-parts-list for the assignment is 
RED 


The DO statement and its corresponding END statement delimit a group of state- 
ments collectively called a do-group. You can specify non-iterative or iterative proc- 
essing of the group. 


When the do-group ends normally, control passes to the next statement that can be 


processed, unless control leaves the do-group by a transfer of control, such as a GO 
TO, RETURN, or LEAVE statement. 
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DO 


>>—D0—_; 
>>—D WHILE (expression_1) 


UNTIL (expression 2) 


UNTIL (expression_2) 


WHILE (expression_1) 


>>—D0——reference = expression_3——> 


TO—expression_4 

BY—expression_5 
BY—expression_5 

TO—expression_4 


REPEAT—expression_| 


WHILE{expression_1) 
UNTIL {expression_2) 
UNTIL(expression_2) 


WHILE(expression_1) 


The type 1 DO statement specifies that the do-group, also called a simple do-group, 
is treated as a single statement. The do-group is processed once. It can be used, for 
example, to specify the THEN- or ELSE-unit of an IF statement. Types 2 and 3 
provide for the iterative processing of the do-group. 


WHILE(expression_1) 
Evaluates to BIT(1). You can either use a bit variable that you have explicitly 
declared, or you can specify a condition, in which case you are implicitly 
declaring a bit variable which the program sets to '1'B or '0'B depending on 
whether the condition is true or false. Each time, before the do-group is proc- 
essed, expression_1 is evaluated. If the value is '1'B, the do-group is processed. 
If the value is '0'B, processing of the do-group ends. 


UNTIL(expression_2) 
Must evaluate to BIT(1). You can either use a bit variable that you have 
explicitly declared, or you can specify a condition, in which case you are implic- 
itly declaring a bit variable which the program sets to '1'B or '0'B depending 
on whether the condition is true or false. Each time, after the do-group is proc- 
essed, expression_2 is evaluated. If the value is '0'B, the do-group is processed. 
If the value is '1'B, processing of the do-group ends. 


reference 
The control variable. It must be a scalar variable of arithmetic or pointer type. 


Expressions in the reference to the control variable, such as subscripts and 
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pointer qualifiers, are evaluated once, outside the do-group. Therefore, the 
location in storage of the control variable is established; it remains unchanged 
while the group is being processed. 


If a reference is made to a control variable after the last iteration is completed, 
the value of the variable will be the value that exceeded the limit set in the DO 
statement. 


expression_3 
Specifies the initial value of the control variable. It must be of arithmetic, 
pointer or string type. 


If the TO, BY or REPEAT options are omitted, the do-group is processed once 
with the control variable having the value of expression_3, or not at all if the 
WHILE option is specified and the value of expression_1 is '0'B. 


TO expression_4 
Specifies the ending value of the control variable. Expression_4 must be an 
arithmetic expression. 


Processing of the do-group ends as soon as the value of the control vanable is 
outside the range defined by the TO or REPEAT options. If the TO option is 
omitted, and the BY option is specified, processing is repeated until it is ended 
by a WHILE or UNTIL option, or until control is transferred out of the do- 


group. 


BY expression_5 
Specifies the increment added to the control variable after the do-group is proc- 
essed. Expression_5 must be an arithmetic expression. 


If the BY option is omitted, and the TO option is specified, expression_5 
defaults to 1. If BY 0 is specified, processing is repeated until it is ended by a 
WHILE or UNTIL option, or until control is transferred out of the do-group. 


REPEAT expression_6 
Each time the do-group is processed, expression_6 is evaluated and assigned to 
the control variable. Processing is repeated until it is ended by the WHILE or 
UNTIL option, or until control is transferred out of the do-group. 
Expression_6 must be of arithmetic, string, or pointer type. 


The TO and BY options allow you to vary the control variable in fixed positive or 
negative increments. In contrast, the REPEAT option, an alternative to the TO 
and BY options, allows you to vary non-arithmetic control variables, such as 
pointers. 


The effect of processing a do-group can be summarized as follows: 


1. If a control variable is specified, the initial value is assigned to it and then any 
BY or TO options are evaluated. This yields the BY and TO values. 


2. If the TO option is specified, the value of the control variable is tested against 
the TO value. The control variable is outside the range and the do-group is 
ended if: 


¢ The BY value is positive and the control variable is greater than the TO 
value. 
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¢ The BY value is negative and the control variable is less than the TO value. 


. If the WHILE option is specified, expression_1 is evaluated. If the value is 


'0'B, the do-group is ended. 


. The statements in the do-group are processed. 


. If the UNTIL option is specified, expression_2 is evaluated. If the value is 


'1'B, the do-group 1s ended. 


. If there is a control variable: 


e If the TO or BY option 1s specified, the BY value is added to the control 
variable. 


¢ If the REPEAT option is specified, expression_6 is evaluated and assigned 
to the control variable. 


¢ Ifthe TO, BY, and REPEAT options are omitted, the do-group is ended. 


. The cycle is repeated from point 2 if the do-group has not been previously 


ended. 


Control can transfer into a type 1 do-group. It can transfer into a type 2 or type 3 
do-group if the GOTO ends a procedure or an on-unit that was called from within 
the do-group. 


The 


maximum depth of do-group nesting is 49. 


Examples of DO Statements 


The 


or the ELSE clause of an IF statement, or in the WHEN statement or the OTHER- 


DO statement can specify a group of statements processed in the THEN clause 


WISE statement in a select-group. For example: 


IF ITEM1 = ITEM2 
THEN DO; 


END; 


ELSE DO INDEX1=1 10 2; 


END; 


A repetitive do-group might take the form: 
DO INDEX1 = 1 TO 10; 


END; 


In this example, the do-group is processed ten times, while the value of the control 
variable INDEX1 ranges from 1 through 10. 
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The following example specifies that the do-group is processed five times, with the 
value of INDEX1 equal to 2, 4, 6, 8, and 10: 


DO INDEX1 = 2 TO 10 BY 2; 


If negative increments of the control variable are required, the BY option must be 
used. For example: 


DO INDEX1 = 10 TO 1 BY -1; 


In the following example, the do-group is processed with INDEX1 equal to 1, 2, 4, 
8, 16, and so on: 


DO INDEX] = 1 REPEAT 2*INDEX1; 


END; 


The WHILE and UNTIL options make successive processings of the do-group 
dependent upon a specified condition. For example: 


DO WHILE (ITEM1 = ITEM2); 


END; 
DO UNTIL (ITEM1 = ITEM2); 


END; 


A crucial difference between DO WHILE and DO UNTIL 1s that DO WHILE 
checks at the beginning of each loop if the specified condition is true, but DO 
UNTIL makes this check at the end of the loop. The result is that in the absence 
of other options, a do-group headed by a DO UNTIL statement is processed at 
least once, but a do-group headed by a DO WHILE statement may not be proc- 
essed at all. That is, the statements DO WHILE (A=B) and DO UNTIL 

(A— = B) are not equivalent. 


Consider the following examples: 
DO WHILE (ITEM1 = ITEM2) UNTIL (ITEM3 = 10); 


If ITEM] is not equal to ITEM2 the first time the DO statement is processed, the 
do-group is not processed at all. If, however, ITEM] is equal to ITEM2, the do- 
group is processed. If ITEM3 is equal to 10 after the do-group is processed, no 
further processing occurs. Process can occur again provided that ITEM3 is not 
equal to 10, and that ITEM] is equal to ITEM2. 


DO INDEX1 = 1 TO 10 UNTIL (ITEM = 1); 
The do-group is processed at least once, with INDEX1 equal to 1. If ITEM] is 


equal to 1 after the do-group is processed, no further processing occurs. Otherwise, 
the default increment (BY 1) is added to INDEX 1, and the new value of INDEX1 
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END Statement 


is compared with 10. If INDEX] is greater than 10, no further processing occurs. 
Otherwise, a new the do-group is processed again. 


DO INDEX1 = 1 REPEAT (2 * INDEX1) UNTIL (INDEX1 = 256); 


The first time the do-group is processed INDEX1 is equal to 1. After this, and each 
time the do-group is processed, the UNTIL expression is tested. If INDEX1 is 
equal to 256, no further processing occurs. Otherwise, the REPEAT expression is 
evaluated and assigned to INDEX1, and the do-loop is processed again. 


DECLARE POINTER POINTER, 
FIRST ADDRESS POINTER, 
1 DATA_ITEM, 
5 INTEGER FIXED DECIMAL (7), 
5 NEXT_ADDRESS POINTER; 


DO POINTER] = FIRST ADDRESS 
REPEAT POINTER1 -> DATA_ITEM 
WHILE (POINTER1 -= NULL()); 


POINTERI = NEXT ADDRESS; 
END; 


This example shows a DO statement used to step along a chained list, where each 
data item processed includes as one of its fields the address of the next item. The 
value FIRST_ADDRESS is assigned to POINTER for the first time the do-group 
is processed. Inside the loop, the address for the next item is assigned to 
POINTER]; and before each subsequent time the loop is processed, DATAITEM 
is defined as being based on POINTER1’s current value. The last item in the 
chained list contains a null address, because there is no following item; therefore the 
value of POINTER is tested before the first and each time the do-group is proc- 
essed; if it is NULL, no further processing occurs. 


DO INDEX1 = 1 TO 10; 
ARRAY1(INDEX1) = INDEX1; 
END; 


This example shows how the control variable of a DO statement can be used as a 
subscript in statements within the do-group, so that each time processing occurs 
successive elements of a table or array are dealt with. This loop sets the first ten 
elements of ARRAY 1 to 1,2,...,10 respectively. 


The END statement and the corresponding PROCEDURE, BEGIN, DO or 
SELECT statement delimit blocks and do-groups. 
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name 
An identifier that designates a statement label or entry constant. 


Each END statement must pair with a PROCEDURE, BEGIN, DO or SELECT 
statement. Pairing is processed outwards from the innermost procedure, begin- 
block, or do-group. For example: 


PROC1: PROCEDURE; 
BEGIN1: BEGIN; 
DO1: DO; 
END; 
END; 


END; 


In this example, the innermost END statement is paired with the DO statement; the 
next END statement, working outwards, is paired with the BEGIN statement; then 
the next END statement is paired with the PROCEDURE statement. 


If END 1s followed by a name, the name must match that of the PROCEDURE, 
BEGIN, DO, or SELECT statement with which it is paired. For example, the 
END statement that is paired with BEGIN1: BEGIN could be written as 


END BEGINI; 


A program ends normally when control reaches the END statement of the first pro- 
cedure called in the program. The program would also end normally if control 
reached a RETURN statement in the first procedure; but RETURN is not usually 
coded in a program's first procedure. 


Processing of a procedure or begin-block ends normally when control reaches the 
END statement for the block. 


Processing of a do-group ends when control reaches the END statement of the 
group for the final time, in accordance with the conditions specified in the DO state- 
ment. 


Processing of a function ends abnormally if control reaches the END statement; a 


RETURN statement must be specified. (See “RETURN Statement” on page 14-4 
for more information.) 


GO TO Statement 


The GO TO statement transfers control to the statement identified by the label- 
reference. 
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“Te T label_reference; —>< 
GOT 


label_reference 
Specifies a label constant, a label variable, or function reference that returns a 
label value. Because a label variable or function reference can have different 
values at time the GO TO statement is processed, control may not always pass 
to the same statement. 


When a GO TO statement transfers control out of a function, the evaluation of the 
expression that contained the corresponding function reference is discontinued. 


Transferring control out of a block using a GO TO statement can sometimes result 
in the ending of several procedures and/or begin-blocks. Specifically, if the transfer 
point specified by the GO TO statement is contained in a block that did not directly 
activate the block being ended, all intervening blocks in the activation sequence are 
ended (see ‘Ending a Procedure” on page 4-11 for details). For example: 


PROC1: PROCEDURE; 
BEGINI: BEGIN; 


CALL PROC2; 


END BEGIN1; 


PROC2: PROCEDURE; 


BEGIN2: BEGIN; 


60 TO OUTSIDE; 
END BEGIN2; 
END PROC2; 
OUTSIDE: ITEN = 0; 


END PROC1; 


In the above example, PROC1 activates BEGIN1, which activates PROC2, which 
activates BEGIN2. In BEGIN2, the statement GO TO OUTSIDE transfers control 
to the statement in PROC] that is labeled OUTSIDE. Because this statement is 
not contained in BEGIN2, PROC2, or BEGIN], all three blocks are ended; 
PROCI1 remains active. Therefore, the transfer of control out of BEGIN2 results in 
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the ending of intervening blocks BEGIN1 and PROC2 as well as the ending of 
block BEGIN2. 


A GO TO statement cannot transfer control to an inactive block. It cannot transfer 
control from outside a do-group to a statement inside a type 2 or type 3 do-group, 
unless the GO TO ends a procedure or on-unit called from within the do-group. 
For definitions of type 2 and type 3 do-groups, see “DO Statement” on page 13-5. 


If you use a label variable or a function reference in a GO TO statement, its value 
must be a valid label, and the block containing the assigned label constant must be 
active. 


The GO TO statement specifies an unconditional transfer of control. If the destina- 
tion of the GO TO is specified by a label variable or a function reference, you can 
use it as a switch. 


Use of the GO TO statement leads to difficulty in debugging and maintaining pro- 
grams because the permanent transfers of control it creates within the program are 
hard to trace. Whenever possible, you should use do-groups and procedures instead 
of GO TO statements. 


The IF statement tests the value of an expression and controls the flow of proc- 
essing according to the result of that test. 


>>—- 1 F—— express ion—THEN—uni de aay 
ELSE—unit_2— 


expression 
Evaluates to BIT(1). If the expression is a condition such as INTEGER! = 0, 
the program evaluates the expression and sets the bit to | if the expression is 
true, and to 0 if the expression is false. Alternatively, the expression can be a 
BIT(1) variable which the program has set to 1 or 0. For instance, you can 
define EOF as a BIT(1) variable with an initial value of 0, and set it to 1 when 
end of file is detected and handled by an ENDFILE on-unit. 


unit 
Each unit is either a single statement (except BEGIN, DECLARE, DO, END, 
PROCEDURE, SELECT, or a directive), a do-group, or a begin block. Each 
unit can contain statements that transfer control (such as GO TO), so that the 
normal sequence of the IF statement can be overridden. 


The IF statement is a compound statement. The semicolon ending the last unit 
also ends the IF statement. 


If the expression evaluates to '1'B, unit_1 is processed and unit_2 is ignored. If the 
expression evaluates to '0'B, unit_1 is ignored and unit_2 is processed, if present. 
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You can nest IF statements by specifying either or both units as IF statements. 
Because each ELSE unit is associated with the innermost unmatched IF in the same 
block or do-group, you may need to specify an ELSE with a null statement to 
achieve a desired sequence of control. 


The maximum depth of IF statement nesting is 49. 


Examples of IF Statements 
IF ITEM1 > ITEM2 
THEN LARGERNO 
ELSE LARGERNO 


ITEM13 
ITEM2; 


In this example, if the value of ITEM] is greater than the value of ITEM2, the 
value of ITEM is assigned to LARGERNO, and the ELSE unit is not processed. 
If the value of ITEM] is less than or equal to the value of ITEM2, the THEN unit 
is not processed, and the value of ITEM2 is assigned to LARGERNO. 


You do not always have to specify an ELSE unit. When in the event that the IF 
condition is false you simply want to pass control to the statement following the IF 
statement, you can omit the ELSE unit. For example: 

IF (ITEM1 = ITEM2) & (ITEM3 = ITEM4) 


THEN CALL PROC1; 
NEXT: ITEM3 = ITEM1 + ITEM2; 


If the expression is true, the CALL statement of the THEN unit calls PROC1 for 
processing. If the expression is false, the THEN unit is not processed and control 
passes directly to the statement labeled NEXT. 


| IBM Extension | 


ITERATE Statement 


The ITERATE statement is valid only within an iterative do-group. The 
ITERATE statement transfers control to the END statement that delimits the itera- 
tive do-group. 


ie 
label_constant 


label_constant 
Must be a label of a containing do-group. If label_constant is omitted, control 
is transferred to the END statement of the do-group immediately containing the 
ITERATE statement. 
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Example of the ITERATE Statement 
QCOUNT: PROCEDURE OPTIONS (MAIN); 

DECLARE SUBJECTSTRING CHARACTER (80), 
STRINGLENGTH | FIXED BINARY (15), 
INDEX1 FIXED BINARY (15), 
INDEX2 FIXED BINARY (15); 

GET EDIT (SUBJECTSTRING) (A(80)); 

STRINGLENGTH = 80; 


/* Remove all Q's from SUBJECTSTRING */ 


MAINLOOP: DO INDEX1 = 1 
REPEAT (INDEX1 + 1) 
UNTIL (INDEX1 = STRINGLENGTH) ; 


IF SUBSTR (SUBJECTSTRING, INDEX1,1) = 'Q' 
THEN ITERATE MAINLOOP; 


/* Replace Q with following character; shift */ 
/* remaining characters left accordingly ay 


DO INDEX2 = INDEX1 TO (STRINGLENGTH - 1); 
SUBSTR (SUBJECTSTRING, INDEX2, 1) 
= SUBSTR (SUBJECTSTRING, INDEX2+1, 1) ; 
END; 


/* String has lost one character */ 
STRINGLENGTH = STRINGLENGTH - 1; 

/* Check character replacing deleted Q */ 
INDEX1 = INDEX1 - 1; 


END MAINLOOP; 
END QCOUNT; 


LEAVE Statement 


The LEAVE statement transfers control from within a do-group to the statement 
following the END statement that delimits the group and ends the do-group. 
LEAVE is valid only within a do-group. 


Ree 
label_constant 


label_constant 
Must be a label of a containing do-group. The do-group that is left is the do- 
group that has the specified label. If label_constant is omitted, the do-group 
that is left is the group that contains the LEAVE statement. 
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The LEAVE statement and the referenced or implied DO statement must not be in 
different blocks. 


Examples of LEAVE Statements 
In the following example, the LEAVE statement transfers control to “next state- 
ment”: 


DO ...3 
LEAVE; 


END; 
next statement; 


In the following example, the statement LEAVE GROUP] transfers control to 
“statement after GROUP”: 


GROUP1: DO INDEX1 = 1 TO 10; 
DO INDEX2 = 1 TO 5; 
IF SAMPLEARRAY (INDEX1, INDEX2) = 0 
THEN LEAVE GROUP1; 
ELSE 
SAMPLEARRAY (INDEX1, INDEX2) = 5; 
END; 
statement within GROUP1; 
END GROUPI; 
statement after GROUPI; 


In the following example, LEAVE MAINLOOP causes processing of MAINLOOP 
to end once the letter Q has been found in SUBJECTSTRING: 
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DECLARE SUBJECTSTRING CHARACTER (80), 


INDEX1 FIXED BINARY (15), 
QSTRINGTOTAL FIXED BINARY (15), 
QPRESENT FIXED BINARY (15) 


STATIC INITIAL (0); 


GET EDIT (SUBJECTSTRING) (A(80)); 
/* Determine if Q is present in string */ 


MAINLOOP: DO INDEX1 = 1 TO 80; 
IF SUBSTR (SUBJECTSTRING,INDEX1,1) = 'Q' 
THEN DO; 
QPRESENT = 1; 
LEAVE MAINLOOP; 
END; 
END MAINLOOP; 


/* Accumulation of total number */ 
/* of strings containing Q ad 


EXIT: QSTRINGTOTAL = QSTRINGTOTAL + QPRESENT; 


In this example, if no Qs are present in SUBJECTSTRING, MAINLOOP is proc- 
essed 80 times, and QPRESENT is left with a value of zero, so that 
QSTRINGTOTAL remains unchanged after QPRESENT is added. Ifa Q is 
present in the string, QPRESENT is set to 1, and the LEAVE statement is proc- 
essed, so that MAINLOOP ends and control is transferred to EXIT. 


ee eee End of IBM Extension es 


The null statement causes no action and does not affect sequential processing. 


If a statement is preceded by a labeled null statement, a GOTO to that label is effec- 
tively a transfer of control to the following statement, even if that statement cannot 
itself be labeled. 


Examples of Null Statements 


The null statement can specify that no action is taken when a condition is raised. 
For example: 


ON ENDPAGE (SAMPLEFILE) ; 


In this example, no action is taken when the ENDPAGE condition is raised for file 
SAMPLEFILE. 
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A null statement can specify that no action is taken in the THEN unit of an IF 
statement. For example: 


IF ITEM1 = ITEM2 
THENs 
ELSE ITEM1 = 15; 
NEXT: ITEM2 = 25; 


In this example, if ITEM1 is equal to ITEM2, control passes to NEXT. If ITEM1 
is not equal to ITEM2, the ELSE unit is processed before control passes to NEXT. 


A null statement can similarly specify that no action is to be taken in the ELSE unit 
of an IF statement. For example: 


IF ITEM1 = ITEM2 
THEN ITEM1 = 15; 
ELSE; 
NEXT: ITEM2 = 25; 


In this example, if ITEM] is equal to ITEM2, the value 15 is assigned to ITEM1. 
If, however, ITEM] 1s not equal to ITEM2, control passes directly to NEXT. 


| IBM Extension | 


SELECT, WHEN, and OTHERWISE Statements 


A select-group provides a multi-way conditional branch. A select-group contains a 
SELECT statement, optionally one or more WHEN statements, optionally an 
OTHERWISE statement, and an END statement. The syntax of the select-group is 
shown below: 


name: (expression _1) 


——WHEN— ( =e | 
Teo toa 
OTHERWISE—unit name 


Abbreviation: OTHER for OTHERWISE 
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name: SELECT (expression_1); 
With its corresponding END statement, SELECT delimits a group of state- 
ments, collectively called a select-group. The optional expression_| in the 
SELECT statement is evaluated and its value is saved. 


WHEN (expression_2) unit 
Specifies an expression or expressions that are evaluated and compared one by 
one with the saved value of expression_1. If an expression is found equal, the 
evaluation of the expressions in the WHEN statements is ended, and the unit of 
the associated WHEN statement is processed. If no such expression is found in 
the WHEN statements, the next statement is processed. 


If expression_1 is omitted, each expression_2 must evaluate to a bit string. If 
the result is '1'B, the unit of the associated WHEN statement is processed. If 
the result is '0'B, the next WHEN statement is evaluated. If all WHEN state- 
ments evaluate to '0'B, the unit of the OTHERWISE statement is processed. 


The WHEN statement must not have a label prefix. 


OTHERWISE unit 
Specifies the unit is processed when every test of the preceding WHEN state- 
ments fails. 


If the OTHERWISE statement is omitted and processing of the select-group 
does not result in the selection of a unit, the ERROR condition 1s raised. 


The OTHERWISE statement must not have a label prefix. 


unit 
Each unit is either a single statement (except BEGIN, DECLARE, DO, END, 
PROCEDURE, SELECT, or a directive), a do-group, or a begin-block. Each 
unit can contain statements that transfer control (such as GO TO); hence, the 
normal sequence of the SELECT statement can be overridden. 


Each unit may be labeled. 


END name; 
Must be specified. It ends the select-group (see “END Statement” on 
page 13-10). 


After processing of a unit of a WHEN or OTHERWISE statement, control passes 
to the statement following the select-group, unless the normal flow of control 1s 
altered within the unit. 


The maximum permissible depth of nesting of select-groups is 49. 


Examples of Select-Groups 
In the following example, E, El, etc., are expressions. When control reaches the 
SELECT statement, the expression E is evaluated and its value is saved. The 
expressions in the WHEN statements are then evaluated in turn (in the order in 
which they appear), and each value is compared with the value of E. If a value is 
found that is equal to the value of E, the action following the corresponding WHEN 
statement is processed; no further WHEN statement expressions are evaluated. If 
none of the expressions in the WHEN statements is equal to the expression in the 
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SELECT statement, the action specified by the OTHERWISE statement 1s proc- 
essed. 


SELECT (E); 
WHEN (E1,E2,E3) action-1; 
WHEN (E4,E5) action-2; 
OTHERWISE action-n; 
END; 
NL: next statement; 


An example of expression_1 being omitted is: 


SELECT; 
WHEN (ITEM1>ITEM2) CALL BIGGER; 
WHEN (A=B) CALL SAME; 
OTHERWISE CALL SMALLER; 

END; 


If a select-group contains no WHEN statements, the action in the OTHERWISE 
statement is processed unconditionally. If the OTHERWISE statement is omitted, 
and processing of the select-group does not result in the selection of a WHEN state- 
ment, the ERROR condition is raised. 


fe ee ee ee End of IBM Extension se sl 


STOP Statement 


The STOP statement abnormally ends the run unit. 


>>—STOP; >< 


When you process the STOP statement, any files in the run unit that are open are 
closed with an error indication. 
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Chapter 14. Procedures, Subroutines, and Functions 


You may wnite your own subroutines and functions (user-defined), or use those pro- 
vided by the PL/I compiler (built-in). 


This chapter describes user-defined subroutines and user-defined functions, and how 
to define, declare, and call them. When not stated to the contrary, references to 
“subroutine” and “function” in this chapter are to user-defined procedures. For 
details about built-in functions and subroutines, see Chapter 15, “Built-In Func- 
tions, Subroutines, and Pseudovariables.” 


Subroutines and functions can: 


° Be called from different points in a program as well as in different programs to 
C process the same frequently used process. 


* Process data passed to them on different calls. 


¢ In the case of subroutines, return control to a point immediately following the 
point of calling or transfer control to another part of the program. 


e In the case of functions, return control and a value to the point of calling or 
transfer control to another part of the program. 


Subroutines and functions can use data known in the calling block and made avail- 
¢ able by: 


¢ Arguments and parameters. References to data in the calling block are passed 
in an argument list to parameters in the called procedure. 


e Names whose scope of declaration includes both the calling block and the called 
procedure (see “Scopes of Names” on page 4-14). 


Cc Defining a Procedure 


You define a procedure by writing a PROCEDURE statement as the first of a 
sequence of statements and an END statement as the last. (See ‘Internal and 
External Procedures” on page 4-9 for a discussion of procedures, and “END 
Statement” on page 13-10 for a discussion of the END statement.) 


Functions 


A function is a procedure that has a RETURNS option in the PROCEDURE 
statement. A function is called by a function reference. It ends normally by proc- 
essing a RETURN(expression) statement and returning a scalar value to the point 
of calling. 
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Subroutines 


A subroutine is a procedure that has no RETURNS option in the PROCEDURE 
statement. A subroutine is called by a subroutine CALL. It ends normally by 
processing either a RETURN statement that has no expression or an END state- 
ment. 


PROCEDURE Statement 
The PROCEDURE statement specifies: 


¢ Any parameters the procedure may have. 
e For an external procedure, any options the procedure may have. 
e For a function, the attributes of the returned value. 


>>—entry_constant:—PROCEDURE 


REENTRANT ee 2 


RECURSIVE 


Abbreviation: PROC for PROCEDURE 


entry_constant 
A name that is the entry name of the procedure. Every procedure must have an 
entry name. The maximum length of an external entry name is 10 characters. 


parameter 
A name that is used to refer to an argument passed to this procedure. It is 
explicitly declared as a parameter by its appearance in a parameter list. See 
“Parameter Attributes” on page 14-3 for how to declare attributes for parame- 
ters. 


The maximum number of parameters any procedure can have is 32, except for 
function procedures, which can have a maximum of 31. 


| IBM Extension | 


A parameter list can be specified for the external procedure. See “Calling a 
PL/I Program from a Non-PL/I Program” on page 2-24. 


(eee End of IBM Extension ee, 
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OPTIONS 
OPTIONS is valid only for an external procedure. If you specify OPTIONS, 
you must include at least one option. 


The options are separated by blanks or commas. 


The options are syntax checked but otherwise ignored. They are provided for 
easy transfer of procedures to other compilers that require them. Although they 
are not required for AS/400 PL/I, you may include them so that your programs 
can be used with other compilers. 


MAIN 
The MAIN option, if specified, is syntax checked but otherwise ignored. 
The usual first statement of a PL/I program is 


Label: PROCEDURE OPTIONS (MAIN); 


REENTRANT 
The REENTRANT option, if specified, 1s syntax checked but otherwise 
ignored. All AS/400 PL/I procedures are reentrant. 


RECURSIVE 
The RECURSIVE option, if specified, is syntax checked but otherwise 
ignored. All AS/400 PL/I procedures are recursive. For more information 
on using recursive procedures, refer to ‘Recursive Procedures” on 
page 14-11. 


RETURNS(attribute) 
The value of the expression in a RETURN statement is converted to the attri- 
butes specified in the RETURNS option before being returned. 


The attributes can specify any scalar data type except FILE. String lengths 
must be specified by integer constants. If you specify the ENTRY attribute, it 
must not have parameter descriptors or a RETURNS attribute. 


Parameter Attributes 


You supply the attributes of a parameter in a DECLARE statement internal to the 
procedure. 


For a parameter or component of a parameter structure that is scalar or an array of 
scalars, you must specify at least one of the following attributes, unless you use * to 
pass the parameter to a non-PL/I routine: 

FIXED CHARACTER 

FLOAT BIT 

BINARY POINTER 


DECIMAL LABEL 
PICTURE ENTRY 


You cannot specify storage class or scope attributes for a parameter. 
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Parameter Lengths and Bounds J 


Lengths of strings and bounds of arrays must be integer constants, or they must be 
specified by means of the asterisk notation (see “BIT and CHARACTER 
Attributes” on page 12-16 and “Arrays and the Dimension Attribute” on 

page 12-38). 


If you specify the string length or an array extent of a parameter by means of an 
asterisk, the length or bounds will be taken from the associated argument. This is 
useful if argument lengths or bounds differ for different calls or if their values are 
known only during processing. 


RETURN Statement 


The RETURN statement ends the procedure that contains it and returns control to 
the calling procedure. In the case of a function, it also returns a value. ) 


en 
(expression) 


expression 
A scalar expression of any data type except FILE. 


A RETURN statement without an expression ends a subroutine. Control returns J 
to the next statement following the point of calling. 


A RETURN statement with an expression ends the processing of a function. The 
expression must have a type that can be converted to the attributes specified in the 
RETURNS option of the procedure statement; that is, the attributes in the 
RETURNS option and the attributes of the expression must both specify a problem 
data type or they must both specify the same program control data type. 


The expression is evaluated and converted to the attributes of the RETURNS J 
option. The resulting value is returned to the point of calling. 


Calling a Procedure 


A function is called by a function reference; a subroutine is called by a subroutine 
call. Both subroutines and functions may be nested up to 50 levels deep. (See 
“Function Reference” below and “CALL Statement” on page 14-7.) 


Function Reference 
A function reference is an entry constant or an entry variable reference followed by a 
possibly empty argument list. The entry constant or entry variable must represent a 
function. 
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>>—entry_reference (argument_list)——>< 


where argument_list is: 


i 


argument 


You can write a function reference wherever an expression is allowed as well as in a 
subroutine call if the function returns an entry value. 


To call a function that has no arguments, specify the function name with an empty 
argument list. Like a subroutine, a function can operate upon the arguments passed 
to it and upon other known data. 


When a function ends normally, by means of a RETURN(expression) statement, 
the value determined by the function is converted, if necessary, to the attributes of 
the RETURNS option of the PROCEDURE statement. The value is then 
returned, with control, to the point of calling. Evaluation of the expression then 
continues. 


The returned value can be any type of scalar data item except a file. 


The examples that follow show entry constants and entry variables used in function 
references. In these examples, the function references call functions that are internal 
to the initial procedure. 


The following example shows an entry constant used in a function reference: 


SKYE: PROCEDURE; 
DECLARE (A,B,C,D} FIXED BINARY (15); 


A = FUN(C,D)*B; 
FUN: PROCEDURE(Q,R) 
RETURNS (FIXED BINARY (15)); 
DECLARE (Q,R) FIXED BINARY (15); 
RETURN (3.1416*Q*R) ; 
END FUN; 
END SKYE; 


In this example, the function reference FUN(C,D) calls the function FUN, with two 
arguments. Argument C is associated with parameter Q, and argument D with 
parameter R. FUN returns the value of 3.1416*Q*R to the function reference. The 
returned value is then multiplied by the value of B, and the result is assigned to A. 


The following example shows an entry variable used in a function reference: 
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EIGG: PROCEDURE; 
DECLARE (A,B,C,D,E) FIXED BINARY (15), 
FUN ENTRY (FIXED BINARY (15)) 
VARIABLE 
RETURNS (FIXED BINARY (15)); 


IF A>B THEN FUN = FUN 1; 
ELSE FUN = FUN 2; 
C = D*FUN(E); 
FUN 1: PROCEDURE (Q) 
RETURNS (FIXED BINARY (15)); 
DECLARE Q FIXED BINARY (15); 
RETURN (3.1416*Q**2); 
END FUN 1; 
FUN 2: PROCEDURE(Q) 
RETURNS (FIXED BINARY (15)); 
DECLARE Q FIXED BINARY (15); 
RETURN (Q**2); 
END FUN 2; 
END EIGG; 


In this example, the entry constant FUN_1 or FUN_2 is assigned to the entry vari- 
able FUN, after the comparison of A and B. The function reference FUN(E) calls 
the appropriate function it has a single argument. Argument E 1s associated with 
parameter Q. The called function returns a value to the function reference. The 
returned value is then multiplied by the value of D and the result is assigned to C. 


The following example shows a pointer-qualified and subscripted entry variable ref- 
erence used in a function reference: 


CARA: PROCEDURE; 

DECLARE 1 A(10) BASED, 
5 B FLOAT BINARY (5), 
5 C ENTRY(FIXED DECIMAL (6)) 

RETURNS (FIXED BINARY (15)), 

5 D FIXED DECIMAL (6); 

DECLARE P POINTER; 

DECLARE I FIXED BINARY (15); 


P->C(3) = FUN; 
I = P->C(3) (13); 
FUN: PROCEDURE (Q) RETURNS (FIXED BINARY(15)); 
DECLARE Q FIXED DECIMAL (6), 
RI FIXED BINARY (15); 


RETURN (RI); 
END FUN; 
END CARA; 


In this example, the entry constant FUN is assigned to element C(3) of the array of 
structures A. The function reference C(3)(13) calls function FUN; it has a single 
argument. The argument, 13, is associated with parameter Q. FUN returns a 
binary fixed-point value, which is then assigned to variable I. 
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CALLING A PROCEDURE 


You use the CALL statement to call a subroutine, if it is user-defined or built-in. 


aed erence oa 
bite ductal ee 
(—argument ) 


entry_reference 
An entry constant, an entry variable reference, or a function reference that 
returns an entry value. In each case, the value of the entry reference must repre- 
sent a subroutine. 


built_in_name 
The name of a built-in subroutine (see “Built-In Subroutines” on page 15-4). 


argument 
A scalar expression or an array or structure reference, which is evaluated in the 
procedure in which the call is processed. There can be no more than 32 argu- 
ments in the argument list. For a function call, there is a maximum of 31 argu- 
ments, because the RETURNS value is implicitly the first argument. | 


If the entry reference is a function reference, it must return a subroutine that does 
not itself have parameters. This is illustrated in the third example below (procedure 
IONA). 


A subroutine call is an entry reference followed by an optional and possibly empty 
argument list that appears in a CALL statement. The entry reference must repre- 
sent a subroutine. 


Whenever a subroutine is called, any arguments of the calling statement are associ- 
ated with the parameters of the procedure (see ‘“‘Association of Arguments and 
Parameters” on page 14-9). Control is then passed to that procedure. The subrou- 
tine is therefore activated and processing begins. 


The examples that follow show entry constants, entry variables, and function refer- 
ences used in subroutine calls, as well as how a subroutine interacts with the proce- 
dure that calls it. In these examples, subroutines are called that are internal to the 
initial procedure. 


The following example shows an entry constant used in a subroutine call: 
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GIGHA: PROCEDURE; 
DECLARE (A,B) FIXED BINARY (15); 


CALL SUB (A); 
B=B+1; 


SUB: PROCEDURE(C) ; 
DECLARE C FIXED BINARY (15); 


IF C < 12 THEN RETURN; 
END SUB; 
END GIGHA; 
In this example, the subroutine call CALL SUB(A) calls the internal subroutine 


SUB. The argument A in the subroutine call is associated with parameter C of the 
procedure SUB. Each reference to C in SUB 1s treated as a reference to A. 


When SUB ends, control passes to the first processable statement following the sub- 
routine call; that is, to the statement B= B+ 1. 


The following example shows an entry variable, which references a subroutine, used 
in a subroutine call: 


ISLAY: PROCEDURE; 
DECLARE SUB ENTRY (FIXED BINARY (15)) 
VARIABLE, 
A FIXED BINARY (15); 


IF A>11 THEN SUB=SUB1; 
ELSE SUB=SUB2; 
CALL SUB (A); 


SUB1: PROCEDURE (B); 
DECLARE B FIXED BINARY (15); 


IF B = 12 THEN RETURN; 


END SUB1; 
SUB2: PROCEDURE (C); 
DECLARE C FIXED BINARY (15); 


IF C> 7 THEN RETURN; 
END SUB2; 
END ISLAY; 
In this example, the internal entry constant SUB1 or SUB2 is assigned to the entry 
variable SUB. The subroutine call CALL SUB(A) calls the internal subroutine 
SUB1 or SUB2 as appropriate. The argument A in the subroutine call is associated 
with parameter B in SUB1 or parameter C in SUB2. Each reference to B in SUB1 
or to C in SUB2 is treated as a reference to A. 


When the called subroutine ends, control passes to the first statement that can be 
processed following the subroutine call; that is, to the statement END ISLAY. 
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The following example shows an entry value that is returned by a function and 
called immediately in a subroutine call: 


TONA: PROCEDURE; 


CALL FUN(13)(); 
FUN: PROCEDURE(A) RETURNS (ENTRY); 
DECLARE A FIXED DECIMAL (6,2); 


IF A>9 THEN RETURN (SUB1); 
ELSE RETURN (SUB2); 
END FUN; 
SUB1: PROCEDURE; 
END SUB1; 
SUB2: PROCEDURE; 
END SUB2; 
STMT1: A = 5; 
END IONA; 


In this example, the function reference FUN(13) calls the internal function FUN. 
The argument 13 in the function reference is associated with parameter A of the 
function FUN. A dummy argument is created because the argument is a constant. 


When FUN ends, control is returned to the subroutine call together with an entry 
value (SUB] in this example), which is then called as a subroutine without parame- 
ters. 


When the subroutine call CALL FUN(13)() ends, control passes to the first 
processable statement following the subroutine call (STMT1 in this example). 


Association of Arguments and Parameters 
When a function or subroutine is called, parameters in the parameter list corre- 
spond, from left to right, to arguments in the associated argument list. The number 
of arguments and parameters must be the same for a PL/I procedure. 


| IBM Extension | 


For an external procedure declared with the ASSEMBLER option, or for a built-in 
subroutine, any number of arguments, from zero through to the number of parame- 
ters, can be passed in the call that calls the routine, but intervening arguments 
cannot be omitted. Note that the ASSEMBLER option means any module that 


can be processed. For example, if routine SUB3 has three parameters, the following 
may be valid: 


CALL SUB3(AFID,BFIB) ; 


However, the following is not valid: 
CALL SUB3(AFIB, ,BFLOD); 


[| On of IBM Extension _—“‘—~‘—~s~C~CSC—~*™Y 
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There is no restriction on the data type of problem data arguments that can be 
passed to problem data parameters. The data type of program control data argu- 
ments must be the same as the program control data parameters to which they are 
passed. 


An argument can be associated with a parameter in any of the following ways: 


¢ By passing a reference to the argument, rather than its value. This is done when 
the argument is a variable whose attributes match those of the corresponding 
parameter, as described below. Any change to the value of the parameter will 
affect the value or the original argument. 


An easy way to force the creation of a dummy argument is to enclose the refer- 
ence in parentheses, thereby turning it into an expression. 


e By creating a dummy argument to which the value of the argument is assigned 
and passing the dummy argument. This is done in the remaining cases; that is, 
when the argument 1s: 


— aconstant 

— an expression with operators or parentheses 

— a function-reference 

— a variable whose attributes do not match those of the parameter. 


The argument is converted, if necessary, to the attributes of the parameter 
before being assigned to the dummy argument. The dummy argument and the 
parameter initially have the same value as the original argument, but any change 
made to the value of the parameter affects only the value of the dummy argu- 
ment. The value of the original argument is unchanged. A reference to the 
parameter is a reference to its dummy argument. 


The parameter attributes used for dummy argument creation and conversion are: 


¢ Those declared for the corresponding parameter, in the case of an internal pro- 
cedure 


¢ Those specified in the corresponding parameter descriptor of the ENTRY attri- 
bute, in the case of an external procedure or entry variable. 


The argument and the parameter are considered to match if they have the same data 
and alignment attributes. If a parameter string length or array bound is specified by 
an integer constant, the corresponding length or bound of the argument must be an 
integer constant with the same value. Ifa parameter string length or array extent is 
specified by an asterisk, the corresponding length or bounds of the argument may 
have any value. 


If a parameter is a scalar, the argument must be scalar. 


If a parameter is an aggregate, the argument must be an aggregate with identical size 
and shape and identical component data types. If an array bound of the parameter 
is specified by an integer constant, the corresponding array bound of the argument 
must be specified by an integer constant with the same value. Therefore, a dummy 
argument will never be created for an aggregate. 
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The rules that govern the creation of a dummy argument for a non-PL/I routine are 
the same as those for a PL/I procedure, except that no dummy argument is created 
for a non-PL/I routine in the following cases: 


¢ When a variable is passed to a parameter that is described by an asterisk. 
¢ When the argument is a file constant. 


For more information about passing arguments to non-PL/I routines, see 
“OPTIONS(ASSEMBLER) Attribute” on page 12-36. 


Recursive Procedures 
An active procedure that can be called from within itself or from within another 
active procedure is said to be a recursive procedure; such a call is termed recursion. 


A procedure that is called recursively should have the RECURSIVE option speci- 
fied in its PROCEDURE statement for compatibility with other implementations of 
PL/I. 


The environment (that is, values of automatic variables, etc.) of every call of a recur- 
sive procedure is ‘pushed down” at a recursive call, and “popped up” at the end of 
that call. A label constant in the current block is always a reference to the current 
calling of the block that contains the label. 


If a label constant is assigned to a label variable in a particular calling, a GO TO 
statement naming that variable in another call would restore the environment that 
existed when the assignment was processed. 


The environment of a procedure called from within a recursive procedure by means 
of an entry variable is the one that was current when the entry constant was 
assigned to the variable. Consider the following example: 


I=1; 
CALL A; /*FIRST CALLING OF A*/ 


A: PROCEDURE OPTIONS(RECURSIVE) ; 
DECLARE EV ENTRY VARIABLE STATIC; 
IF I=1 THEN 

DO; 


CALL A; /*2ND CALLING OF A*/ 
END; 
ELSE CALL EV; /*CALLS B WITH 
ENVIRONMENT OF FIRST 
CALLING OF A*/ 
B: PROCEDURE; 
GO TO OUT; 
END B; 
OUT: END A; 


The GO TO statement in the procedure B will transfer control to the END A state- 
ment in the first calling of A, and will therefore end B and both calls of A. 
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Effect of Recursion on Automatic Variables 


The values of variables allocated in one activation of a recursive procedure must be 
protected from change by other activations. A stack operates on a last-in first-out 
basis. The most recent generation of an automatic variable is the only one that can 
be referenced. Static variables are not affected by recursion. Therefore they are 
useful for communication across recursive calls. This also applies to based variables 
and to automatic variables that are declared in a procedure that contains a recursive 
procedure. For example: 


A: PROCEDURE; 
DECLARE X ... ; 


B: PROCEDURE OPTIONS(RECURSIVE) ; 
DECLARE Z ... , 
Y STATIC; 
CALL B; 


END B; 
END As; 


A single generation of the variable X exists throughout calls of procedure B. The 


variable Z will have a different generation for each call of procedure B. The variable 
Y can be referred to only in procedure B and will not be reallocated at each call. 
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Chapter 15. Built-In Functions, Subroutines, and 
Pseudovariables 


The built-in functions, subroutines and pseudovariables are described in alphabetical 
order later in this chapter. In general, each description has the following: 


¢ The syntax of the reference 


e A description of the value returned by the built-in function or the target identi- 
fied by the pseudovariable 


¢ Details of the arguments 


¢ Any other qualifications on the use of the function, subroutine or 
pseudovariable. 


The arguments may be expressions. The arguments are evaluated, checked for 
correct attributes, and converted if necessary to a form suitable for the built-in func- 
tion, subroutine, or pseudovariable according to the rules for data conversion. 


Arguments must be scalar, except for those that indicate that they accept aggregates 
or structures (see ‘Aggregate Arguments” on page 15-5). 


Declaring a Built-In Function or Built-In Subroutine 
A built-in function or built-in subroutine can be declared explicitly or contextually. 
They are explicitly declared in a DECLARE statement by the BUILTIN attribute. 
A built-in function is contextually declared by a built-in function reference that con- 
tains an argument list; a built-in subroutine is contextually declared by a built-in 
subroutine call with an optional argument list. 


Some built-in functions have two names: a full name and an abbreviated name. 
Each has a separate declaration (explicit or contextual) and name scope, like any 
two other names. Although both refer to the same built-in function, you can use 
both names in built-in function references in the same block. 


Built-In Functions 


A built-in function is a predefined function that is called by a built-in function refer- 
ence. A built-in function reference is a built-in function name with an optional, 
possibly empty, argument list. It represents the value returned by the built-in func- 
tion. 


>>—built_in_function_name 


¥en 
argument ) 
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If the built-in function has arguments associated with it, you must specify an argu- - 
ment list that has the number of arguments required by the built-in function. If the 

built-in function has no arguments, you may specify the empty argument list or 

omit the argument list. 


Built-in functions include the commonly used arithmetic functions and other neces- 
sary or useful functions related to language facilities, such as functions for manipu- 
lating strings or converting data. 


Classification of Built-In Functions 
The built-in functions are classified as follows: 


Computational built-in functions 
String handling 
Arithmetic ' 
Mathematical ») 
Array handling 

Condition handling 

Storage control 

Input/output 

Miscellaneous 


String Handling Built-In Functions 


The string handling built-in functions simplify the processing of bit and character J 
values. They are: 

BIT SUBSTR 

CHARACTER TRANSLATE 

COPY UNSPEC 

INDEX VERIFY 

LENGTH 


Arithmetic Built-In Functions 


The arithmetic built-in functions control the conversion of base, scale, and preci- 
sion, and determine the properties of arithmetic values. The arithmetic built-in 
functions are: 


ABS MAX 
BINARY MIN 
DECIMAL MOD 
DIVIDE ROUND 
FIXED SIGN 
FLOAT TRUNC 


Some of these functions derive the data type of their results from one or more argu- 
ments. When the base or scale of the arguments differ, they are converted to their 
common base and scale. If the scales differ, fixed-point is converted to floating- 
point. If the bases differ, decimal is converted to binary. 
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Except where otherwise stated, picture arguments are converted to fixed-point 
decimal. 


To determine the target precision of an argument that is to be converted to an arith- 
metic type, refer to Figure 12-4 on page 12-27. If the argument is: 


e Bit, use FIXED BINARY(31) as the source. 
¢ Character, use FIXED DECIMALK15,0) as the source. 


For functions that give a binary fixed result or a floating-point result, the precision 
specified does not cause rounding or truncation of the result. It does, however, 
determine the storage requirements of the result (see Figure 5-1 on page 5-10). 


Mathematical Built-In Functions 


The mathematical built-in functions provide mathematical operations. They are: 


ACOS LOG2 
ASIN LOG10 
ATAN SIN 
ATAND SIND 
ATANH SINH 
COs SQRT 
COSD TAN 
COSH TAND 
EXP TANH 
LOG 


These functions operate on floating-point values to produce a floating-point result. 
Any arithmetic argument that is not floating-point is converted (see “Data 
Conversion” on page 5-27). 


The range of values for each argument of the mathematical built-in functions can be 
found listed with the function. 


Array Handling Built-In Functions 


The array handling built-in functions operate on array arguments and return a scalar 
value. The array may have inherited dimensions. The array handling built-in func- 
tions are: 


DIMENSION LBOUND 
HBOUND 


Condition Handling Built-In Functions 


The condition handling built-in functions allow you to investigate the cause of a 
raised condition. Use of a condition handling built-in function is in context when 
within an on-unit or dynamic descendant of an on-unit whose activation sets the 
value of the function. This is described for each condition handling built-in func- 
tion below. See also “Scope of Values of Condition Handling Built-In Functions” 
on page 10-4. The condition handling built-in functions are: 
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ONCODE ONKEY 
ONFILE 


Storage Control Built-In Functions 


The storage control built-in functions allow you to identify the location of a vari- 
able, or create a null pointer value, or calculate the amount of storage (in bytes) 
allocated to a variable. The storage control built-in functions are: 


ADDR STORAGE 
NULL 


Input/Output Built-In Functions 


The input/output built-in functions allow you to determine the current state of a 
file. They are: 


LINENO 
SAMEKEY 


Miscellaneous Built-In Functions 


The built-in functions that do not fit into any of the foregoing classes are: 


DATE PLISHUTDN 
PLIRETV TIME 


Built-In Subroutines 


A built-in subroutine is a predefined routine that provides access to facilities of the 
operating system. It is called by a CALL statement (see “CALL Statement” on 
page 14-7). 


You can explicitly declare a built-in name to have the BUILTIN attribute (see 
“BUILTIN Attnbute” on page 12-36). 


The built-in subroutines, and their uses, are: 


| IBM Extension | 


PLIDUMP Gives a symbolic dump of the variables of the currently running 
PL/I program. 
PLIRETC Allows a program to receive a PL/I program return code. 


bo End of IBM Extension oe ee ce 


PLICOMMIT Establishes a commitment boundary and processes commitment 
control functions. 
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( PLIIOFDB Copies information from the system-defined I/O feedback area. 
PLIOPNFDB Copies the system defined open feedback area. 


PLIRCVMSG Returns information about the original message that caused the 
calling of an on-unit. 


PLIROLLBACK Reestablishes a previous commitment boundary and processes 
commitment control functions. 


You can explicitly declare a built-in name to have the BUILTIN attribute (see 
“BUILTIN Attribute” on page 12-36). 


Pseudovariables 
Pseudovariables represent targets for assignments. A pseudovariable can appear 
only on the left of the assignment symbol in an assignment statement. 


C The pseudovariables are SUBSTR and UNSPEC. 


Pseudovariables cannot be nested. For example, the following statement is not 
valid: 
UNSPEC(SUBSTR(A,2,1)) = '04'B4; 


Aggregate Arguments 
: The built-in functions that can accept aggregate arguments are ADDR and 
CC STORAGE, and if the aggregate is an array, DIMENSION, HBOUND, and 
LBOUND. 


Empty Argument Lists 
Some built-in functions do not require arguments. You must declare these either 
explicitly with the BUILTIN attribute or contextually by including an empty argu- 
ment list in the built-in function reference, as in ONKEY(). The name cannot oth- 
erwise be recognized as a built-in function name. 


CC You specify an empty argument list by following the function name with an open 
parenthesis followed immediately by a close parenthesis. 


Descriptions of Built-In Functions, Subroutines and Pseudovariables 


Unless otherwise noted, the following items are built-in functions. Options enclosed 
within square brackets are optional. 


ABS(x) 


ABS returns the absolute value of x. 


x 
An arithmetic or picture expression. 


( The value returned by ABS is the absolute value of x. The result has the base, 
scale, and precision of x. 
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ACOS(x) 


ADDR(x) 


ASIN(x) 


ACOS returns a floating-point value that represents the arc cosine, in radians, of x. 
x 

An arithmetic or picture expression, where ABS(x) < 1. 
The result is in the range: 

0 < ACOS(x) < pi 


and has the base and precision of x. 


ADDR returns a pointer value that identifies the location of the variable x in 
storage. 


x 
A reference to a variable of any data type, data organization, alignment, and 
storage class. In a reference to an array with inherited dimensions, subscripts 
for the inherited dimensions must be specified. 

If x is a reference to: 


¢ An aggregate, the returned value identifies the first structure field or array 
element. 


e A component of an aggregate, the returned value takes into account subscripting 
and structure qualification. 


¢ A based level-1 variable, the result is the value of the pointer that explicitly 
qualifies x (if it appears) or that is associated with x in its declaration. 


¢ A parameter for which a dummy argument has been created, the returned value 
identifies the dummy argument. 


¢ A varying-length character string, the returned value points to the halfword 
prefix at the beginning of the string. 


ASIN returns a floating-point value that represents the arc sine, in radians, of x. 
x 

An arithmetic or picture expression, where ABS(x) < 1. 
The result is in the range: 

-pi/2 < ASIN(x) < pi/2 


and has the base and precision of x. 
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L 


C 


ATAN(x{,y]) 


ATAND(x{,y]) 


ATANH(x) 


ATAN returns a floating-point value that represents the arc tangent, in radians, of x 
or of the ratio x/y. 


X,Y 
Arithmetic or picture expressions. 

If you omit y, the result has the base and precision of x and is in the range: 
-pi/2 < ATAN(x) < pi/2 


If you specify x and y, they must not both be zero. The result for all other values 
of x and y has the common base of the arguments. x and y are converted to the 
base and scale of the result. The result precision is the larger of those of the con- 
verted arguments. The value is given by: 


ATAN (x,y) for y>0 

pi/2 for y=0 and x>0 
-pi/2 for y=0 and x<0 
pitATAN(x,y) for y<O and x20 
-pitATAN(x,y) for y<0 and x<0 


Therefore ATAN(x,y) returns the value, in the range 
-pi < ATAN(x,y) < pi 


of the point with rectangular coordinates y and x. 


ATAND returns a floating-point value that represents the arc tangent, in degrees, of 
x or of the ratio x/y. 


X,Y 
Arithmetic or picture expressions. 


If you specify x alone, the result has the base and precision of x and is in the range: 
-90 < ATAND(x) < 90 


If you specify x and y, the value of the result is given by: 
(180/pi) * ATAN(x,y) 


See “ATAN(x[,y])” for the requirements of the arguments and the attributes of the 
result. 


ATANH returns a floating-point value that has the base and precision of x, and 
represents the hyperbolic arc tangent of x, in radians. 


x 
An arithmetic or picture expression. 


The result has a value given by: 
LOG( (1+x) /(1-x)) /2 
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BINARY(x{,p[,0]]) 
Abbreviation: BIN 


BINARY converts x to a binary value with a precision specified by p. 


x 
An arithmetic or string expression. 


An integer constant that specifies the number of digits of the result. It must not 
exceed the implementation limit (31 for fixed-point or 53 for floating-point). 


You must specify p if x is fixed-point decimal or pictured with a nonzero scale 
factor. 


If you omit p, the precision of the result is the converted precision of x (see 
Figure 12-4 on page 12-27). 


If x is arithmetic, the scale of the result is that of x. If x is a string, the scale of the 
result is fixed-point binary. 


BIT(xL,y]) 
BIT converts x to a bit string with a length specified by y. 
x 
An arithmetic or string expression. When a character string expression is useG, 
it must contain only ones and zeros. 
Af 
An integer expression with a non-negative value. If you omit y, BIT determines 
the length according to the rules for type conversion (see “Data Conversion” on 
page 5-27). If y=0, the result is a null bit string. 
CHARACTER(xLy]) 
Abbreviation: CHAR 
CHARACTER converts x to a character string with a length specified by y. 
x 
An arithmetic or string expression. 
Y 
An integer expression with a non-negative value. If you omit y, CHARACTER 
determines the length according to the rules for type conversion (see “Data 
Conversion” on page 5-27). If y=0, the result is a null character string. 
COPY (x,y) 


COPY returns a string consisting of y concatenated copies of the string x. 


x 
A string expression. 
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COS(x) 


COSD(x) 


COSH(x) 


DATE[()] 


y 
An integer expression with a non-negative value that specifies the number of 


repetitions. 


If y is zero, the result is a null string. 


COS returns a floating-point value that has the base and precision of x and repres- 
ents the cosine of x, in radians. 


x 
An arithmetic or picture expression whose value is in radians. 


COSD returns a floating-point value that has the base and precision of x and repres- 
ents the cosine of x, in degrees. 


x 
An arithmetic or picture expression whose value is in degrees. 


COSH returns a floating-point value that has the base and precision of x, and 
represents the hyperbolic cosine of x, in radians. 


Xx 
An arithmetic or picture expression. 
The result is in the range: 


+1 < COSH(x) < + infinity 


DATE returns a character string of length 6, in the form yymmdd, where: 


yy the last two digits of the current year 
mm__ the current month 
dd the current day 


DECIMAL(x{[,p[,q]]) 


Abbreviation: DEC 


DECIMAL converts x to a decimal value with a precision specified by p and q. 


X 
An arithmetic or string expression. 


Pp 
An integer constant that specifies the number of digits of the result. It must not 


exceed the implementation limit (15 for fixed-point or 16 for floating-point). 
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DIMENSION(x, y) 


DIVIDE(x,y,p[,q]) 


q 
An integer constant that specifies the scale factor of the result. For a fixed-point 


result, if you specify p and omit q, a scale factor of zero is assumed. For a 
floating-point result, q must be omitted. 


If you omit both p and gq, the precision of the result is the converted precision of x 
(see Figure 12-4 on page 12-26). 


If x is arithmetic, the result has the scale of x. If x is a string, the scale of the result 
is decimal fixed-point. 


Abbreviation: DIM 
DIMENSION returns a fixed-point binary value of precision (15,0) that specifies the 
extent of dimension y of array x. 


x 
An array reference. The array can have inherited dimensions. 


y 
An integer constant that specifies a particular dimension of x. 


X must not have fewer than y dimensions. y must be greater than or equal to 1. 


As the lower bound of an array dimension is always 1, the extent of the dimension 
is the same as its upper bound. Therefore DIM(x,y) is equal to HBOUND(x,y). 


DIVIDE returns the result of x divided by y. The precision of the result is specified 
by p and q. 


x 
An arithmetic or picture expression that represents the dividend. 

y 6 e e e e 
An arithmetic or picture expression that represents the divisor. If y=0, the 
zerodivide condition is raised. 

P e 
An integer constant that specifies the number of digits to be maintained 
throughout the operation. It must not exceed the maximum number of digits 
allowed for the base and scale of the result. 

q 


An integer constant that specifies the scale factor of the result, which must be 
fixed-point decimal. If you omit q, the DIVIDE built-in function assumes a 
scale factor of zero. q must be zero, if specified, for a fixed-point binary result 
or omitted for a floating-point result. 


If either x or y is fixed-point binary, the other expression must not be fixed-point 
decimal with a nonzero scale factor. 
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EXP(x) 


FIXED(x,p[,q]) 


FLOAT(x,p) 


HBOUND(x,y) 


The base and scale of the result are the common base and scale of x and y. 


EXP returns a floating-point value that represents the base e of the natural loga- 
rithm system raised to the power of x. 


x 
An arithmetic or picture expression that is the power to which the base is raised. 


The result has the base and precision of x. 


FIXED converts x to a fixed-point value with a precision specified by p and q. 


x 
An arithmetic or string expression. 


An integer constant that specifies the number of digits of the result. It must not 
exceed the implementation limit (15 for decimal or 31 for binary). 


An integer constant that specifies the scale factor of the result. If you omit q, 
the FIXED built-in function assumes a scale factor of zero. 


For a binary result, q must be zero, if specified. 


If x is a string, the base of the result is binary for a bit string and decimal for a 
character string. Otherwise, the result has the base of x. 


FLOAT converts x to a floating-point value with a precision specified by p. 


Xx 
An arithmetic or string expression. 


p 
An integer constant that specifies the number of digits of the result. It must not 
exceed the implementation limit (16 for decimal or 53 for binary). 


If x is a string, the base of the result is binary for a bit string and decimal for a 
character string. Otherwise the result has the base of x. 


HBOUND returns a fixed-point binary value of precision (15) that specifies the 
upper bound of dimension y of array x. 


x 
An array reference. The array can have inherited dimensions. 


y 
An integer constant that specifies a particular dimension of x. 


X must not have fewer than y dimensions. y must be greater than or equal to 1. 
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INDEX(x,y) 


LBOUND(x,y) 


LENGTH(x) 


LINENO(x) 


LOG(x) 


INDEX returns a binary fixed-point value of precision (15), which indicates the 
starting position within string x of a substring identical to string y. 


x 
A string expression that specifies the string searched. 


y 
A string expression that specifies the string searched for. 


If y does not occur in x, or if either x or y has zero length, INDEX returns the 
value zero. 


If y occurs more than once in x, INDEX returns the starting position of the left- 
most occurrence. 


Both arguments must be bit strings or both must be character strings. 


LBOUND returns a fixed-point binary value of precision (15) that specifies the 
lower bound of dimension y of the array x. This value is always 1. 


x 
An array reference. The array can have inherited dimensions. 


y 
An integer constant that specifies a particular dimension of x. 


X must not have fewer than y dimensions. y must be greater than or equal to 1. 


LENGTH returns a fixed-point binary value of precision (15) that specifies the 
length of string x. 


x 
A bit expression or a character expression. 


LINENO returns a fixed-point binary value with precision (15) that specifies the 
current line number of file x. 


X 
A file constant. The file must be open and have the PRINT attribute. 


LOG returns a floating-point value that has the base and precision of x and repres- 


ents the natural logarithm (that is, the logarithm to the base e) of x. 


x 
An arithmetic or picture expression greater than zero. 
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__ LOG2(x) 


LOG? returns a floating-point value that has the base and precision of x and repres- 
ents the binary logarithm (that is, the logarithm to the base 2) of x. 


x 
An arithmetic or picture expression greater than zero. 


LOG10(x) 


LOG1O returns a floating-point value that has the base and precision of x and 
represents the common logarithm (that is, the logarithm to the base 10) of x. 


x 
An arithmetic or picture expression greater than zero. 


CC MAX(x1,x2) 


MAX returns the greater of x1 and x2 
x1,x2 
Arithmetic or picture expressions. 


If either x1 or x2 is fixed-point binary, and the other is fixed-point decimal or 
picture, the other must have a scale factor of zero. 


| The result has the common base and scale of x1 and x2. The arguments are con- 
( verted to the base and scale of the result. 


If the converted arguments are fixed-point with precisions: 
(p1,q1) , (p2,q2) 
the precision of the result is given by: 


p = MIN(n,MAX(pl-ql,p2-q2) + MAX(q1,q2)) 
q = MAX(q1,q2) 


( where n is the maximum number of digits allowed (decimal 15, binary 31). For 
binary, ql = q2 = 0. 
If the converted arguments are floating-point with precisions: 
pl,pe 


the precision of the result is given by: 
p = MAX(p1,p2) 


MIN(x1,x2) 
MIN returns the smaller of x1 and x2. 


x1,x2 
Arithmetic or picture expressions. 
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MOD(x,y) 


NULL[()] 


ONCODE[()] 


If either x1 or x2 is fixed-point binary, and the other is fixed-point decimal or 
picture, the other must have a scale factor of zero. 


The result has the common base and scale of x1 and x2. The arguments are con- 
verted to the base and scale of the result. 


The precision of the result is the same as for the MAX built-in function. 


MOD returns the remainder obtained by dividing x by y, with the sign of y. If 
y=0, MOD returns x. 


X,Y 
Arithmetic or picture expressions. 


If either x1 or x2 1s fixed-point binary, and the other is fixed-point decimal or 
picture, the other must have a scale factor of zero. 


For y— = 0, the result of MOD is x-y*floor(x/y), where floor(x/y) is the largest 
integer less than or equal to x/y. 


The result has the common base and scale of x and y. The arguments are converted 
to the base and scale of the result. 


If the result is floating-point, the result precision is the greater of those of x and y. 
If the result is fixed-point, the result precision is given by: 

p = MIN(n, p2-q2+MAX(q1,q2) ) 

q = MAX(q1,q2) 


where (pl1,q1) is the precision of x and (p2,q2) that of y after any necessary conver- 
sion, and n is the maximum number of digits allowed (15 for decimal or 31 for 
binary). For binary, ql = q2 = 0. 


NULL returns the null pointer value. 


The null pointer value cannot identify any variable. 


ONCODE returns a fixed-point binary value of precision (15), which is the current 
condition code. 


Whenever an on-unit for a condition is entered, the condition code is set to a value 
that describes the situation that raised the condition. If ONCODE is used out of 
context, it returns zero. 


Conditions and condition codes are described in Appendix D, ‘Conditions and 
Condition Codes.” Condition handling is described in Chapter 10, “Condition 
Handling Statements.” 
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; .. ONFILE[()] 


ONFILE returns a character string, which is the name of the file for which an 
input/output or conversion condition has been raised. 


The value of ONFILE is set when an on-unit is entered for any of the following 
conditions: 


e An input/output condition 
e The conversion condition raised during an input/output operation 
e The ERROR condition raised as the implicit action for such a condition. 


If ONFILE is used out of context, it returns the null character value. 


ONKEY[()] 

ONKEY returns a character value, which is the key of the record for which an 

eS input/output condition has been raised. The value of ONKEY is set whenever an 
on-unit is entered for an input/output condition (except ENDFILE) caused by an 
input/output statement that contained the KEY or KEYFROM(expression), or for 
the ERROR condition raised as implicit action for such a condition. If the KEY or 
KEYFROM(expression) is not specified, or if KEYFROM(*) is specified, ONKEY 
returns a null character value. The variable returned may contain numeric and char- 
acter fields. For CONSECUTIVE files, the BIN(31) value is converted to a char- 
acter value and returned. For files which contain multiple key fields, each field is 
concatenated with the next field. Numeric fields appear in internal form unaligned. 


Se The result is determined according to the following rules: 


e The result is the key of the record that was processed by the input/output state- 
ment that caused the error. 


¢ For the READ statement, the value in the KEY option is returned. If the value 
for NBRKEYFLDS in the OPTIONS option is less than the maximum for the 
record, the full KEY value may not be returned. 


¢ For the WRITE statement, the value in the KEYFROM option is returned. 


( e For the REWRITE or DELETE statement with the KEY option specified, the 
value in the KEY option is returned. 


Note: If the duplicate key condition 1s raised by the REWRITE statement, the 
key value in the key option, and the key value imbedded in the record may not 
be the same, therefore the ONKEY built-in function may not return the value 
of the duplicate key. 


If ONKEY is used out of context, it returns the null character value. 


PLICOMMIT Built-In Subroutine 


The PLICOMMIT built-in subroutine processes commitment control functions. 


>>—CALL—PLI ee Wecsanil 
(character_expressian) 
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character_expression 
A character expression that can be converted to a non-varying character vari- 
able. A character string of zero length is equivalent to not specifying the argu- 
ment. 


For more information about how to use PLICOMMIT, see “Commitment 
Control” on page 8-58. 


| IBM Extension | 


PLIDUMP Built-In Subroutine 
The PLIDUMP built-in subroutine produces a symbolic dump of the variables of 
the currently running PL/I program. 


ON 
(‘options_list TOT 
user_identification 


The program variables that are dumped depend on the options you specify when 
you call PLIDUMP. The dump also contains: 


° A list of any ONCODE, ONFILE, or ONKEY data which is relevant 
e The date and time of the dump 
¢ The statement number from which the dump was called. 


You can also request this dump whenever the program encounters a system error 
that is not handled by o0s/400 or by the program. 


For a complete description of how to use PLIDUMP, see “Using PLIDUMP” on 
page 3-14. 


es, End of IBM Extension se tn ee oe 


PLIIOFDB Built-In Subroutine 
The PLIJOFDB built-in subroutine copies the system defined I/O feedback area. 


>>—CALL—PLIIOFDB(file_constant,reference)—;——>« 


file_constant 
The declaration file name. 


reference 
Either a non-varying scalar or a connected structure reference that will contain 
the feedback data. If a structure reference is used, all binary fields in the struc- 
ture should be declared UNALIGNED. If the length of the reference supplied 
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c 


is less than the feedback data available, the data is truncated. If the length is 
greater than the feedback data available, the remaining portion of the reference 
is not modified. 


The system defined I/O feedback area contains information about the last I/O oper- 
ation processed, including: 


¢ The last record format read 
¢ The major and minor return codes from communications and display processing 
¢ The last data base record key read. 


The system defined I/O feedback area consists of a common area and a device- 
specific area. 


The structure of these areas is shown in the Programming: Control Language Pro- 
grammer's Guide. 


PLIOPNFDB Built-In Subroutine 


The PLIOPNFDB built-in subroutine copies the system defined open feedback 


area. 


>>—CALL—PLIOPNFDB(file_constant,reference)—;—»< 


file_constant 
The declaration file name. 


reference 
Either a non-varying scalar or a connected structure reference that will contain 
the feedback data. Ifa structure reference is used, all binary fields in the struc- 
ture should be declared UNALIGNED. If the length of the reference supplied 
is less than the feedback data available, the data is truncated. If the length is 
greater than the feedback data available, the remaining portion of the reference 
is not modified. 


The first time a file is opened, system feedback information about the file is copied 
into the open feedback area. The content of the open feedback area does not 
change as long as the file status does not change. 


The open feedback area contains information such as: 


e The name of the library, file, and member opened 
¢ The type of file opened 
¢ For data base files: 

— Duplicate keys allowed 

— Duplicate key order 

— Commitment control information. 


The structure of the system defined open feedback area is shown 1n the Program- 
ming: Control Language Programmer's Guide. 
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PLIRCVMSG Built-In Subroutine 


PLIRCVMSG returns the message identifier, message data record and message refer- 
ence key for the last escape or notify message that resulted in the calling of an 
on-unit. PLIRCVMSG is intended for use in an on-unit to determine the source of 
the error. This may be useful because multiple system messages may map to one 
PL/I condition code. 


message_id 
A character variable that will contain the system message identifier of the last 
escape or notify message. This should be seven characters long. 


message_data 
A character variable that will contain the message data record. The message 
data record contains the substitution values (in a single character string) that 
were used in the text of the received message. This data varies with each 
message. If the length of the variable supplied is less than the message data 
available, the data will be truncated. If the length is greater than the message 
data available, the remaining portion of the variable will not be modified. 


message_reference_key 
A character variable that will contain the message reference key that identifies 
the message. This should be four characters long. 


PLIRCVMSG will return the 0S/400 escape or notify message that called the 
on-unit. STATUS messages cannot be received from a program message queue. If 
a STATUS message is the cause of the on-unit call, PLIRCVMSG will set the 
message identifier field to blanks. If the PL/I compuer is originating the condition 
the message returned will be a PL/I defined message. 


If the original message was CPF9999, PLIRCVMSG will return the message identi- 
fier, message data record, and message reference key of the escape message that 
caused CPF9999. 


If PLIRCVMSG is not used within an on-unit, it will return blanks in the variables. 
If PLIRCVMSG 1s called multiple times within an on-unit, it will return the same 
values as the previous use. 


i a ial IBM Extension OT 


PLIRETC Built-In Subroutine 
PLIRETC passes a return code from a called PL/I program to the program that 
called the PL/I program. The return code is passed in the return code field in the 
Work Control Block (wcB). This allows the passing of the return code either for 
examination by a program (BASIC, CL, PL/I, RPG) in a subsequent job step or it may 
be used to indicate conditions that were encountered while running. 
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PLIRETV[()] 


>>—CALL—PLIRETC (express{on)—_;—>< 


expression 
An expression which is converted to FIXED BINARY (15,0). 


The return code generated by a PL/I program consists of a BIN(15) field and is 
passed to PL/I program management (PL/I) with a call to PLIRETC. At the begin- 
ning of a run-unit the return code field in the WCB is set to zero. Thereafter PL/I 
will only store a value in the WCB when a run-unit ends abnormally, or when the 
program stores a specified return code by calling PLIRETC. 


If PL/I ends abnormally the return code indicates the way in which the program 
ended, unless an error is detected which prevents the PL/I program management rou- 
tines from operating correctly. Therefore if PL/I ends normally any value set using 
PLIRETC or which was set by a called lower level procedure will remain in the 
return code in the WCB. 


When a PL/I program calls PLIRETC, the argument (return code value) can be 
either a constant or a variable with the attributes FIXED BINARY (15,0). 


The following table shows the values and meanings of the return codes generated by 
the PL/I program management routines. Any values greater than 0, other than those 
in the following list was set either by PLIRETC or by a called procedure. 


Return Meaning 


Code 

0 Normal ending. 

2 STOP statement, or a call to PLIDUMP with the S option. 

3 ERROR condition raised and run-unit ended with return fom ERROR 
on-unit or no active ERROR on-unit was found. 

4 PL/I program management routines detected an error which did not 


allow the ERROR on-unit to be called. 


a ee End of IBM Extension See Se ee eee ol 


PLIRETV returns a fixed-point binary value of precision (15,0) that is the PL/I 
return code. 


The value of the return code is one of the following: 


e The last value specified by a CALL PLIRETC statement. 
e The value returned by an external procedure. 
« Zero. 


An empty argument list may be used to declare the function as BUILTIN. 
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PLIROLLBACK Built-In Subroutine 


PLISHUTDN{[()] 


ROUND(x,y) 


The PLIROLLBACK built-in subroutine processes the rollback function by rees- 
tablishing a previous commitment boundary. 


»>>—CALL—PLIROLLBACK— ; >< 


For more information on PLIROLLBACK, see “Commitment Control” on 
page 8-58. 


PLISHUTDN returns a BIN(15) FIXED variable which indicates the system status 
request to end the program. 


A value of 127 indicates that a controlled cancel is pending. A value of 0 indicates 
that no cancel is pending. 


An empty argument list may be used to declare the function as BUILTIN. 


If the CL command ENDJOB is issued with *CNTRLD specified as the OPTION 
parameter, the job does not end until the length of time specified in the DELAY 
parameter has passed. 


The value of x is rounded at the digit position specified by y. 


X 
A fixed-point decimal or picture expression with a nonzero scale factor. 


y 
A non-negative integer constant that specifies the digit position at which the 


value is rounded; that is, at digit y to the right of the decimal point. 


The precision of the fixed-point result is given by: 


p = MAX(1,MIN(p-qtl+y, 15)) 
q=y 


where (p,q) is the precision of x. 


The result has the base and scale of x. 
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SAMEKEY(x) 
The SAMEKEY built-in function is included for compatibility with other imple- 
mentations of PL/I. AS/400 allows you to find a common file key by specifying 
POSITION (NXTEQL) on the OPTIONS option of an input/output statement 
(see “POSITION Parameter” on page 7-17). 


SAMEKEY returns a bit value of length | that indicates if a record that has been 
accessed is followed by another with the same key. 
x 


A file constant. The file must have the RECORD attribute. 


Upon successful completion of an input/output operation on file x or immediately 
before raising the ERROR condition, the value accessed by SAMEKEY is set to 
'1'B if the record processed is followed by another record with the same key. Oth- 
erwise, the value is set to '0'B. 


The value accessed by SAMEKEY is also set to '0'B if: 


¢ The file does not have the attributes INDEXED, RECORD, and INPUT or 
UPDATE. 


¢ An input/output operation that raised a condition other than ERROR also 
changed or lost file positioning. 


¢ The file is not open. 
¢ A current file position does not exist. 


¢ A current file position is the last record in the file in the direction of data 
transfer. 


Note: a return value of '1'B only guarantees that the next record has the same key 
at the time the value was returned. It does not guarantee that the key will be the 
same when you access it, or that you will be able to access the record even if the 
key is the same. 


ns ee oe see End of IBM Extension ee 


SIGN(x) 
SIGN returns a fixed-point binary value of precision (15) that indicates if x is posi- 
tive, zero, or negative. 


x 
An arithmetic or picture expression. 


The returned value is given by: 
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SIN(x) 


SIND(x) 


SINH(x) 


SQRT(x) 


STORAGE(x) 


Value ofx Value Returned 


x > Q +1 
x = 0 0 
x <Q -j 


SIN returns a floating-point value that has the base and precision of x and 
represents the sine of x, in radians. 


x 
An arithmetic or character expression with a value measured in radians. 


SIND returns a floating-point value that has the base and precision of x and 
represents the sine of x in degrees. 


x 
An arithmetic or character expression with a value measured in degrees. 


SINH returns a floating-point value that has the base and precision of x, and 
represents the hyperbolic sine of x, in radians. 


x 
An arithmetic or character expression with a value measured in radians. 


SQRT returns a floating-point value that has the base and precision of x and 
represents the positive square root of x. 


x 
An arithmetic or character expression. The value of x must not be less than 
zero. 


| IBM Extension | 


Abbreviation: STG 


STORAGE returns a fixed-point binary value of precision (31,0) giving the 
implementation-defined storage, in bytes, allocated to a variable x. 


x 
A connected variable of any data type, data organization, alignment, and storage 
class. 
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SUBSTR(x,y[,Z]) 


If x is a varying-length string, the value returned by STORAGE(x) is the sum of the 
length-prefix of the string and the number of bytes in the maximum length of the 
string. If x is an aggregate containing varying-length strings, the value returned by 
STORAGE(x) is the sum of the length prefixes of the strings and the number of 
bytes in the maximum lengths of the strings. 


fed ee oe ee End of IBM Extension se el 


The SUBSTR built-in function returns the substring, specified by y and z, of string 
X. 


x 
A bit or character expression. 
y e e . * e oe e e 
An integer expression that indicates the starting position of the substring in x. 
z 


An integer expression that specifies the length (number of bits or characters) of 
the substring in x. If zis a negative constant then a compile time error will 
occur. If z is the zero constant or is a variable and is assigned a negative value, 
then a null string is returned. If z is omitted, the substring extends to the end of 
X. 


Assuming that x, y, and z represent their corresponding values, the following 
relationship is true: 

l1<y < length(x)+1 

0 <z < length(x)-y+ 1 


Therefore, the starting position y may be one position after the end of the string if 
the length of the substring is zero. 


Cc SUBSTR(x,y[,2]) Pseudovariable 


The SUBSTR pseudovariable identifies the substring, specified by y and z, of the 
string variable x. You can use the SUBSTR pseudovariable as the target in an 
assignment statement to assign a string value to the substring. 


x 

A reference to a string variable. 
y e 

An integer expression that indicates the starting position of the substring in x. 
Z 


An integer expression that specifies the length of the substring in x. If x isa 
negative constant then a compile time error will occur. Ifz is the zero constant 
or is a variable and is assigned a negative value, then a null string is returned. If 
z 1s omitted, the substring extends to the end of x. 


The same relationships must hold for the arguments as are given for the SUBSTR 
built-in function. 
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TAN(x) 
TAN returns a floating-point value that has the base and precision of x and 
represents the tangent of x, in radians. 


x 
An arithmetic or picture expression whose value is in radians. 


TAND(x) 
TAND returns a floating-point value that has the base and precision of x and 
represents the tangent of x, in degrees. 


x 
An arithmetic or picture expression whose value is in degrees. 


TANH(x) 


TANH returns a floating-point value that has the base and precision of x, and 
represents the hyperbolic tangent of x, in radians. 


x 
An arithmetic or picture expression whose value is in radians. 


The range of the result is: 


-1 < TANH() < +1 


TIME[Q)] 
TIME returns a fixed-length character string of length 9, hhmmssttt, where: 


hh the current hour 

mm the current minute 

SS the current second 

ttt the current millisecond 


TRANSLATE(x, y[,2]) 


TRANSLATE returns a character string of the same length as x; the characters are 
translated according to the correspondence described by y and z. 


x 

A character expression that specifies the string translated. 
y 

A character expression that specifies the characters into which to translate. 
Zz 


A character expression that specifies the characters from which to translate. If z 
is omitted, a string of 256 characters is assumed. The string contains the 
EBCDIC characters in ascending collating sequence (hexadecimal 00 through 
FF). 


y is padded with blanks or truncated on the right to match the length of z. 
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C 


c 


TRUNC(x) 


UNSPEC(x) 


TRANSLATE translates each character of x as follows: 


A character that occurs in z is translated into the character that occurs at the corre- 
sponding position in y. Any character that does not occur in z is left unchanged. 
(If a character occurs in z more than once, the leftmost occurrence is considered.) 


For example: 

DECLARE (W, X) CHAR (3); 
X="ABC!; 

W = TRANSLATE (X, 'TAR', 'DAB'); 


In the above example, W is equal to 'ARC'. 


TRUNC returns an integer that is the truncated value of x. If x is greater than or 
equal to zero, the result is the largest integer less than or equal to x. If x is negative, 
the result is the smallest integer greater than or equal to x. 


x 
An arithmetic or picture expression. 


The base, scale, and precision of the result match those of x, except when x 1s fixed- 
point decimal with precision (p,q). The precision of the result is given by: 

p = MIN(15,MAX(p-q+1,1)) 

q 


The UNSPEC built-in function returns a bit value that is the internal coded form of 
the value represented by x. 


x 
A reference to a scalar variable. 


The length of the returned bit value depends on the data type of x. If x is of type 
BIT(n), the length of the returned value is n. For any other data type, the length of 
the returned value is 8*n bits, where n is the length of x in bytes, as defined in 
Figure 5-1 on page 5-10. 


UNSPEC(x) Pseudovariable 


The UNSPEC pseudovariable identifies a target that is variable x considered as a bit 
variable. 


x 
A reference to a scalar variable. 


The length of the bit variable is the same as for the UNSPEC built-in function. If 
UNSPEC(x) is used as the target in an assignment statement, the source value is 
converted to a bit value. The bit value is considered the internal representation of 
the value of x. It is assigned directly to x, without conversion, and is padded or 
truncated to the length of UNSPEC(x) according to the rules for bit assignment. 
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VERIFY(x,y) 
VERIFY returns a fixed-point binary value of precision (15) that indicates the posi- 
tion in x of the leftmost character that is not in y. If all the characters in x appear 
in y, VERIFY returns a value of zero. If x is the null string, VERIFY returns a 


value of zero. If x is not the null string and y is the null string, VERIFY returns a 
value of 1. 


x 
A character expression that specifies the string scanned. 


y 
A character expression that specifies the characters searched for. 
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Appendix A. Compiler Service Information 


This appendix is provided for PL/I service personnel to use when investigating PL/I 
compiler problems and provides the following information: 


¢ Compiler overview 

¢ Compiler debugging options 

¢ IRP layout 

¢ Quantitative limits of the compiler. 


PL/I programmers can also use this information to investigate PL/I compiler prob- 
lems on their own before, or instead of, calling for service. 


c Compiler Overview 


This section provides the following compiler information: 


¢ How the compiler works 

¢ Compiler description 

¢ Description of major compiler data area 
e Organization of compiler error messages. 


, This section provides an internal view of the compiler. If you need an external view 
< to investigate a PL/I problem, see Chapter 2, “Creating, Compiling, and Running 
Your PL/I Program,” which describes entering a PL/I program into the system, 
compiling your program and using the listings that the compiler produces. 


Figure A-1 on page A-2 summarizes how a PL/I source program is compiled into a 
program object. 
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PL/I Source 
Statements 


1. The PL/I compiler converts the source 
Statements into various forms of 
intermediate text. 


Various 
Forms of 
Intermediate 
Text 


2. The compiler converts the various forms of 
intermediate text into IRP (intermediate 
representation of the program). 


IRP 


3. The PRM (program resolution monitor) 
converts the IRP program object code, 
called a program template. 


Program 
Template 


4, The program template is converted 
(translated) into a program that can 
be run, called a program object. 


Program 


Object 


Figure A-l. Overview of the Compilation of a PL/I Program. 


The various forms of intermediate text are representations of PL/I source statements 
that are created by the compiler and exist only during compilation. 


You can use the SERVICE parameter of the CRTPLIPGM command to list the 


various forms of intermediate text. See “Compiler Debugging Options” on 
page A-10 for explanations of this parameter and examples of intermediate text. 
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When you compile the program, you can use the *LIST value for the GENOPT 
parameter on the CRTPLIPGM command to list the Intermediate Representation 
of the Program (IRP). See “Compiler Debugging Options” on page A-10 for an 
explanation of this parameter and examples of an IRP listing. 


When you compile the program, you can use the *DUMP value for the GENOPT 
parameter on the CRTPLIPGM command to list the program template. 

See “Compiler Debugging Options” on page A-10 for an explanation of this 
parameter and an example of a program template listing. 


Compiler Organization 
The compiler consists of a number of modules, phases, and segments. Their 
relationships are shown in Figure A-2. 


QPCPLIC This module is called when 
(Command Interface Module) the CL command CRTPLIPGM is 


processed. 
QPCRTOO1 
(Root Module) 


Compiler Phases See Figure A-3 on page A-4 
(QPCZZ001 through QPCTM001) for a description of the 

and segments compiler phases, and 

(1 through 19) Figure A-4 on page A-6 for a 
description of the relationship 
between phases and segments. 


This module calls the 
compiler phases. 


Figure A-2. Overview of the PL/I Compiler 


The phases process the source statements and break them down into various forms 
of intermediate text. The various forms of intermediate text are stored in segments. 


Compiler Phases 
The compiler phases are described in Figure A-3 in the order that they are called 
sequentially under the control of the root module. Each name consists of the fol- 
lowing parts: 


1. The prefix QPC 
2. Two characters that identify the phase 
3. The suffix 001 
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Phase | Phase Description 


QPCZZ001 | The service phase. Allows compiler debugging to be done. 
This phase is called only if SERVICE (*YES) is specified on 
the CRTPLIPGM command. 


QPCLP001 | The low level parse phase. Parses program source statements 
into tokenized text. 

QPCHP001 | The high level parse phase. Parses tokenized text into Polish 
text. 

QPCSV001 | The sort symbol vector phase. Sorts parsed symbols by name, 
block number, and statement number. 


QPCDBO001 | The dictionary build, name resolution, and cross-reference 
phase. Builds the dictionary, processes name resolution, and 
prepares the cross-reference list. 


QPCDX001 | The first de-nesting phase. Processes Polish text, and com- 
pletes the dictionary build. 

QPCDY001 | The second de-nesting phase. Tests both Polish text and cross 
references, and produces a cross-reference listing. 

QPCEA001 | The expression analysis phase. Analyzes expressions for 
validity. 

QPCGC001 | The global check phase. Verifies that expressions and refer- 
ences are contextually correct. 

QPCAG001 | The aggregate processing phase. Maps aggregates and adjust- 
able strings, and prints the aggregate table. 

QPCAD001 | The addressing expansion phase. Processes addressing expan- 
sion functions. 

QPCDIO001 | The DO and IF statement processing phase. Replaces DO, IF 
and END statements of do-groups by n-address text. 

QPCST001 | The stream I/O processing phase. Processes GET and PUT 
statements. 

QPCRCO00I | The record I/O processing phase. Processes file control blocks 
and file constants. 

QPCFLO001 | The flow of control processing phase. Generates prolog code 
for procedures, blocks, and ON statements. 

QPCTROO1 | The text transformation phase. Generates FIT (Final Interme- 
diate Text). 

QPCSK001 | The skeleton identification phase. Translates FIT into EFIT 
(Extended Final Intermediate Text). 


Figure A-3 (Part 1 of 2). Compiler Phase Descriptions 
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Phase Phase Description 
QPCSA001 | The storage allocation phase. Determines the layout of run- 
time storage and produces IRP text for declarations. 
QPCDC001 | The define constant section phase. Converts constants to 
internal format and produces IRP text for constant declarations. 
QPCCGO001 | The code generation phase. Produces IRP text for processable 
Statements. 


QPCFAO001 | The final assembly phase. Calls the PRM (program resolution 
monitor) and produces the program object. 

QPCTMO001 | The end phase. Provides the diagnostic output (messages) and 
ends the program compilation. 


¢ Figure A-3 (Part 2 of 2). Compiler Phase Descriptions 


Intermediate Text 


The compiler phases break down the source statements into various forms of inter- 
mediate text. Some types of intermediate text are: 


Polish text 
N-Address text 


: Constant strings 
4 | Symbol vectors 


The text is stored in segments (see “Compiler Segments” below) by the phases. It 
may be formatted and listed by using the SERVICE parameter of the 
CRTPLIPGM command (see “Compiler Debugging Options” on page A-10) and 
the IBM-supplied formatters (see ““Formatters and Intermediate Text” on 

page A-9). 


Compiler Segments 
Cc The various forms of intermediate text are stored in segments. There are 19 seg- 
ments which are implemented as MI (machine interface) space objects. Each 
segment may have different contents at different times in the compilation. The 
relationship between phases and the contents of segments is shown in Figure A-4 
on page A-6. The figure appears in two parts. It breaks at the DI phase: for 
clarity, this phase is repeated where the second part begins. 
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Figure A-4 (Part 1 of 3). Relationships between Phases and Segments 
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Figure A-4 (Part 2 of 3). Relationships between Phases and Segments 
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Description of Symbols 


previous phase produces 
or changes B 


following phase uses B 
as input 


alternate path 


internal workspace 


Figure A-4 (Part 3 of 3). Relationships between Phases and Segments 


Key Segment Name 


Dictionary 

Cross reference 

EA stack 

DI stack 

DC associated space 
Constant string 

Name string 

Back translate 

Do nesting list 

Symbol vector 
Dictionary for temporaries 
Tokenized text 
Primary text 

Primary text 

Secondary text 
Secondary text 

Block nearness array 
Pre-dictionary elements 
LP member stack space 
Parameter vector 
Where used 
Qualification list 


SHCHMPOVOZZOAC-TOMMIAPY 


xX Branch point list 
Y Reorder vector 
Z Error messages 
Al Work space 

A2 IRP 
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C Formatters and Intermediate Text 
Formatters format and list the various forms of intermediate text so it can be used 
for debugging. Formatters are named like phases, except that the three digit number 
prefix may be any one from 001 through 019. The formatters and their descriptions 
are shown in Figure A-5. 


[Formate [Format Decivies 

QPCPF008 | Formats and lists Polish-1 text, N-Address-1 text, FIT (final 
intermediate text), and EFIT (extended final intermediate text). 

QPCPF009 | Formats and lists Polish-2 text and N-Address-2 text. 


QPCDF003] The dictionary formatter. Formats and lists information 
about each identifier in the program. 


( QPCTFO001 | The tokenized text formatter. Formats and lists a condensed 
representation of the source program consisting of fixed-length 
tokens. 


QPCCF001 | The constant string formatter. Formats and lists all the 
literals (arithmetic and string constants). 


Figure A-5. Compiler Segment Formatters 


é Error Message Organization 
Error message numbers indicate the compiler phase from which they are called. 
Figure A-6 lists the range of the message numbers that are called from each phase. 


[Pine [Meage Range 


Figure A-6 (Part 1 of 2). Error Messages Called by Compiler Phase 
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Message Range 


QPCDIO0! | 4800-5099 
QPCSTOO01 | 5100-5399 


Figure A-6 (Part 2 of 2). Error Messages Called by Compiler Phase 


Compiler Debugging Options 


The GENOPT and SERVICE parameters of the CL command CRTPLIPGM can 
be used to help debug PL/I problems. For information on the other parameters, see 
“Compiling Your Source Program Using the CRTPLIPGM Command” on 

page 2-5. For examples of debugging information that can be requested by these 
parameters, see “Examples of Using Compiler Debugging Options” below. 


Examples of Using Compiler Debugging Options 


Figure A-7 on page A-11 shows examples of debugging information that can be 
requested on the CL command CRTPLIPGM using the GENOPT keyword. The 
compiler listing in Figure A-7 on page A-11 was printed using a CRTPLIPGM 
command that specified debugging parameters as follows: 


CRIPLIPGM QTEMP/LP1413 PLITST/PLISRC + 
OPTION(*XREF *OPT *AGR *ATR) + 
GENOPT(*LIST *XREF *PATCH *DUMP *ATR *DIAGNOSE) 


The program compiled can be seen at Figure 8-3 on page 8-5. The parameters 
specified for the keyword OPTION are discussed at “Compiler Output” on 
page 2-19. 
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aa a 880715 GENERATED OUTPUT 01/25/88 13:18:52 PAGE 3 
1 2 3 

SEQ INST OFFSET GENERATED CODE *... ... Tae ts Giclees tan Binds cbs WSs See Baas tele eee 7... es. 8 BREAK 
90001 TITLE "IBM AS/400 PL/I 5728PL1 ROIMQO IRP LISTING FOR LP1413 ° ; 
90002 ENTRY * (*7500000) EXT ; 
90003 & DCL SPCPTR *76P0100 PARM ; 
ep0e4 DCL SPCPTR *76P0200 PARM ; 
90005 DCL SPCPTR *76P0300 PARM ; 
90006 DCL SPCPTR *76P0400 PARM ; 
0007 DCL SPCPTR *76P0500 PARM ; 
90008 DCL SPCPTR *76P0600 PARM ; 
90009 DCL SPCPTR *76P0700 PARM ; 
90010 DCL SPCPTR *76P@800 PARM ; 
90011 DCL SPCPTR *76P0900 PARM : 
90012 DCL SPCPTR *76PQAG@ PARM : 
90013 DCL SPCPTR *76PQB00 PARM : 
90014 DCL SPCPTR *76P@CO0 PARM : 
90015 DCL SPCPTR *76P0D00 PARM ; 
80016 DCL SPCPTR *76PGE00 PARM ; 
90017 DCL SPCPTR *76POF0Q PARM ; 
90018 DCL SPCPTR *76P1000 PARM ; 
90019 DCL SPCPTR *76P1100 PARM ; 
80020 DCL SPCPTR *76P1200 PARM : 
00021 DCL SPCPTR *76P1300 PARM ; 
g0022 DCL SPCPTR *76P1400 PARM ; 
90023 DCL SPCPTR *76P1500 PARM ; 
pee24 DCL SPCPTR *76P1600 PARM ; 
90025 DCL SPCPTR *76P1700 PARM : 
90026 DCL SPCPTR *76P1800 PARM 
90027 DCL SPCPTR *76P1900 PARM 
90028 DCL SPCPTR *76P1A00 PARM ; 
90029 DCL SPCPTR *76P1B00 PARM ; 
90030 DCL SPCPTR *76P1CO0 PARM 
00031 DCL SPCPTR *76P1000 PARM 
90032 DCL SPCPTR *76P1E00 PARM 
90033 DCL SPCPTR *76P1FG0 PARM 
90034 DCL SPCPTR *76P2000 PARM 
90035 DCL OL *7500000 (*76P0100,*76P0200,*76P0300, *76P0400 , *76P0508, *76P0600 


»*76P07060,*76P0800,*76P0900, *76P 0A00, *76P0B00, *76P0C00, *76P0D00, 
*76PO0E00,*76PGF00,*76P1000, *76P1100,*76P1200,*76P1306,*76P 1400, 
*76P1500,*76P1600,*76P1700,*76P1800,*76P1900,*76P1A00,*76P1B08, 
*76P1C00, *76P1D00,*76P1E00,*76P1F00,*76P2000) PARM EXT MIN(0) ; 
/* DISPLAY ARRAY (FOR ACTIVE BLOCKS) */ 


00036 ; 
00037 DCL DD *DSPAREA CHAR(32) BDRY(16) AUTO ; 
90038 DCL SPCPTR *DISPLAY(2) POS(1) DEF (*DSPAREA) : 
/* QPGADE -- ARRAY DESCRIPTOR */ 
80039 ; 
00040 DCL MSPPTR *ADE@ ; 
60041 DCL DD *ADE BAS(*ADE@) CHAR(204) INT ; 
90042 DCL DD *ADEHDR DEF(*ADE) CHAR(14) ; 
00043 DCL DD *ADEDADE DEF(*ADE) POS(15) CHAR(190) ; 
00044 DCL DD *ADECHDR DEF(*ADEDADE) CHAR(10) ; 
00045 DCL DD *ADECD DEF(*ADECHDR) BIN(2) ; 
00046 DCL DD *ADETL DEF(*ADECHDR) POS(3) BIN(4) ; 
90047 DCL DD *ADERVO DEF(*ADECHDR) POS(7) BIN(4) ; 


Figure A-7. Examples of Compiler Debugging Information 


The *LIST value for the GENOPT parameter causes printing of IRP and machine 
instructions when compilation ends. The headings in this IRP listing indicate the 
following information: 


SEQ: A sequential numbering of the IRP statements. Error messages such as 
IRP syntax errors issued by the program resolution monitor use this number 
to refer to the IRP statements in error. 
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INST: A sequential numbering of the machine instructions generated from 
the IRP statements. Not all IRP statements generate machine instructions. 
The instruction number can be used as a breakpoint for 0s/400 debugging 
functions. See “Using Debug” on page 3-10, or the Programming: Control 
Language Programmer's Guide for information about breakpoints. 


OFFSET: Displacement of the machine instruction into the instruction 
portion of the program template. 


GENERATED CODE: Machine instructions that have been generated from 
IRP statements. 


GENERATED OUTPUT: IrpP statements. 


He & 


BREAK: Breakpoints in the IRP that can be used for stopping points in 
os/400 debugging functions. If the breakpoint is a number, it indicates the 
PL/I source statement that the IRP statement was generated from. 
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5728SS1 RO1 M06 888715 GENERATED OUTPUT 61/25/88 13:18:52 PAGE 3 
ie ODT NAME SEQ CROSS REFERENCE (* INDICATES WHERE DEFFINED) 
i 


QGE3 .AUG6661 248* 

Q0E9 .AU888G2 254* 

Q@GE7 .BAGGG01 252* 

QGED .BAG@G062 258* 

QGE2 .BLK@OO1 247* 248 249 256 251 252 438 439 446 441 442 446 450 451 452 453 695 826 912 
BBE8 .BLK@O@2 253* 254 255 256 257 258 455 456 696 1125 1141 
8OCF .DBGPTR1 223* 

60D@ .DBGPTR2 224* 

GOES .EX8@001 256* 

OGEB .EXG0062 256* 

OGE6 .PA00Q01 251* 

BOEC .PABOO02 257% 

0186 .STATIC@ 424* 425 426 427 431 432 433 534 535 565 566 
QOE4 .ST6GG81 249* 

QGEA .STO0Q02 255% 

@19A .010000C 445* 

819E .6160018 449* 

8198 .A@20008A 443* 

0199 .020000B 444* 

819C .020000E 447* 

@19D .028800F 448* 

0196 .0300012 434* 844 896 897 1137 

6191 .0300013 435* 824 1136 1137 

8192 .0300014 436* 825 843 844 

819B .090000D 446* 447 448 449 865 876 888 
@197 .0900009 442* 443 444 445 875 886 
O18F .6900011 433* 434 435 436 

018D .4700006 431* 826 827 832 849 864 866 867 887 889 896 899 
818E .4700008 432* 828 829 858 879 881 882 904 
8193 .7D00004 438* 837 

@1A3 .7D00615 455* 

0187 .7E80008 425* 823 

01FO *ADDEXTC 661 624* 

8026 *ADE 4i* 42 43 

8025 *ADE@ 40* 41 

802E *ADEBDE 49* 50 51 52 

802D *ADEBDS 48* 49 

@02A *ADECD 45% 

0029 *ADECHDR 44* 45 46 47 

0028 *ADEDADE 43* 44 48 

0027 *ADEHDR 42* 

Q@02F *ADELB 50* 

6031 *ADEMULT 52* 

@O2C *ADERVO 47* 

@62B *ADETL 46% 

8030 *ADEUB 51* 

@1DD *ALCSTAT 538 561* 

O1DE *ALSNOEX 568 570* 

®1DC *ALSNSI 560* 562 574 

O1F5 *AXCEND 649 653* 

@1F3 *AXCNPEC 646 650* 

Q@1EB *AXCNSI 619* 625 654 

@1F4 *AXCNTEC 644 653* 

Q1EE *AXCPNAM 622* 65@ 

O1F2 *AXCPSET 627 636 638* 

@1F1 *AXCSAME 628 637* 


The *XREF value for the GENOPT parameter causes printing of the cross- 
reference listing. The headings in this listing include: 


ODT: The variable number assigned by the PRM to each variable of the IRP. 
E} ODT NAME: The name of the variable in IRP. 
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5728S8S1 RO1 MOO 880715 GENERATED OUTPUT 01/25/88 13:18:52 PAGE 3 
OFFSET MI TEMPLATE DISPLAY 
00000008 Q00035DC 80000000 62010307 FIF4F1F3 404640468 40404040 48404048 48464048 
00000020 40404040 40404040 80000000 00000000 6000015F 00016000 80000000 aon00000 
00000040 08000008 0000000 00542A2F 5£000400 80000008 80000000 80800000 0000808 
860000060 668040FC 80000000 00000000 92120270 00000100 08000107C 60061A40 80000009 
00000080 Q00001B8 00003424 00000000 080000073 600026B8 90000008 80000212 90000000 
QO00000A0 00000000 80000008 80000000 80000008 A0000000 AN00000 ADH00000 «aaD00000 
§00000C0 Q0000000 80000800 0000008 80080008 80000000 HH000000 80000000 00080000 
Q00000E0 00000000 00000000 80000000 80000000 00000008 80000008 e0000000 80000000 
00000100 QOOOOF7C 229301CD O0O00OCC 3C46C000 00812000 601BB1042 60812001 302200CD 
00000120 @1BC1011 40EF00081 22930202 O800GO0CC 22A10000 213201CC OOCC1OBE 00232000 
00000140 @54701C5 00002001 013201CB 01C60083 O1BFO1BE 20001CC2 C@0001C1 61CEO1CF 
00000160 00830068 01022010 1CE24000 007FOQ00 O1CFICD2 CO00007F O1CBOICF 6132007F 2 
00000180 00001011 61022283 61C30000 60000083 086801C2 20100132 O808E01CB 054701C5 ) 
000001A0 068002000 1042008A 01C91042 O008BO1C8 025201C4 0000107B 81CA01D0 01012083 
000001C8 00660074 20001197 00952040 002201A5 @1CBO083 O1A901A5 O1A81CE2 40000080 
000001E0 000001D3 00830186 00802000 00830098 61862000 10B2009B 20801011 61CC2293 
080000200 Q@1DD0000 O0CC3011 01CC2132 O1D400CC 114300A6 200F1193 @0A701D9 1C469000 
00000220 O8OA600A8 810B1043 O1D500A6 3FFF1193 01D601DA 114701D5 20A00032 01D700A4 
00000240 00620107 01051042 O0A80105 30110104 213201DC O80OCCO082 805D01BA 008300A4 
00000260 80602000 00830186 O06COBA6 00830098 01862000 114300A6 O05F1C46 900000A6 
00000280 QOA8O1DE 029301D8 OOO00OCC 30BEG099 200010B2 609A0061 10B2009D 00620293 
000002A0 Q1E20000 O0CC3011 O1DC2132 O1DFOOCC O082009F 61880082 00A20189 O08300AA 
860002C0 00500065 104201E0 20013C46 100001E0 O006001EA 0808300C5 00772000 008300BB 
800002E0 QOOC500CB 104201E1 20013CC2 4Q0000BF OOACO1E7 1C464000 O1E100CA 61£51C46 
00000300 AQQ001E1 OOC801E6 808300BB OOBBOOC4 114301E1 20011011 61£43C46 400000C7 
00000320 BFFFO1E6 008300C5 007008C7 008300BB O0C500CB 104201E1 20011011 01642293 ; 
60000340 Q1FO0000 OOCC2083 00A30070 OOBD1OB2 O0A02088 101101E9 208300A3 007000BD 
80000360 10B200A0 20001CC2 CO0Q00C2 OOB801E8 1CC2C000 OOBFO061 01E80083 00500070 
00000380 QOBD0O83 00530098 20602083 OBAAODDAA QOBA0O83 OO9FOO9F 20010083 OOA200A2 
000003A0 20101143 01£02001 101101E3 301101DF 213201EB O8CCO083 O0A40071 20001C46 
000003C0 400000C8 200001F2 1C462000 OOC800CA 01F11042 GOC7O0A6 809200C5 00A61143 
000003E8 Q0A62200 029301D8 A800000CC 304200C7 BFFFO083 OOBBOOC5 O0CB1042 60C82000 
00000400 101101F2 208300BB OO0BBO0C4 30B200BE O0AB1042 QOOBDO0A6 114300BD 06C81143 
00000426 QOAG00C1 114300A6 00C00293 01D80000 OOCC3CC2 COOOR0C2 O0B801F4 00830050 
90000440 807000BD 1CC2C000 OOBFO061 01F30132 605201CB 00830053 00982000 101101F5 
00000460 30B301EE OGBF2040 01640052 O1EC0000 00000132 00530000 314300C8 20011011 
00000480 Q1EB2132 O1FG0OCC O08300A4 O0GF2000 114300A6 200F1193 O0A701F9 104201F7 
Q000004A0 00461143 O0A60034 1C€469000 O0AG00A8 O1FA0293 01080000 O0CC2083 0038006E 
800004C0 Q1F700A2 003A0076 10B2003C 80350132 004100CD 01320044 01CB0022 06450098 
Q00004E0 01320046 90000132 00474024 00900132 60480000 10820049 00361042 e04A0096 j 
80000500 10B2004B 00371062 O04CO0A6 10BE004D 20000022 00760038 01324024 60900076 
00000520 11930095 20BF1011 0O1F62132 O1FBOOCC 1042003B 00832083 0038006E 003B0083 
00000540 4024004A 00382000 1€461000 00382000 O1FD0132 O0E24024 20010132 00E84024 
06000560 20020083 00380076 20001011 O1FB2132 O1FEOOCC 00830038 00762000 00920076 
00000580 003A0132 4024004A 60470132 QOCDO041 O8300A4 O06F2000 O0A200A6 00381011 
G8OG005A0 Q1FE2132 O206800CC 1CEGCODO 00760075 02041C46 40000097 20000203 10420086 
€00005CO 02010283 40670201 O00B00DA 213201C2 68880132 61C10689 1197608) 20803011 
Q00005E0 02002083 60380076 20000083 O205006E O03A1CE6 CQ000205 00750208 60824085 
80000600 20010206 10420086 00060283 406700D6 OQODDODA 30220041 82091011 40E1004A 
00000620 3C2A4000 003F2080 02070293 92020000 O0CC22A1 20012083 00380076 20001C2A 
00000640 2000003E 2040020B 10220041 O620A3011 40E1004A 30B2020C 60841042 6086020) 
00000660 02834067 @20D0000 8ODA1OB2 9084020C 054701C5 00002003 01320218 601C703E1 
00000680 020E3042 00860200 02834067 02000000 @ODA3Q0B2 O10FOOF6 1842010E 20480293 
000006A0 O21E0000 01053011 OOCC30B2 O1OFOOFF 1842010E 204A0293 021E0000 01053011 
6800006C0 BOCC3O0B2 O1OFOOF7? 1042010E 204B0293 621£0000 01053011 O0CC30B2 O10FOOFA 
G00006E0 1042010E 20480293 021£0000 01053011 O80CC3042 610£2048 98293021E 60000105 


SEQ CROSS REFERENCE (* INDICATES WHERE DEFINED): The 
lines in the IRP listing where the variable is referenced. The * indicates where 


the declaration for the variable is found. 


J 


The *DUMP value for the GENOPT parameter causes printing of the program tem- 
plate. This template shows: 
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OFFSET: The displacement from the beginning of the program template of 
this line of data. The offset is displayed in hexadecimal notation. 


MI TEMPLATE DISPLAY: The data contained in the program template 
at the offset specified. The data is displayed in hexadecimal notation. 


Using the SERVICE Parameter 
You can specify SER VICE(*YES) on the CRTPLIPGM command to access facili- 
ties to debug the PL/I compiler in batch or interactive mode. 


You can debug in batch mode by creating a source file member to contain the 
debugging commands you want to use. You must name this source file member 
QPLIDBGINP, and place it in the same library as the program source file. 


You can debug interactively in any of the following ways: 


¢ Debug in batch mode by entering debugging commands in source file member 
QPLIDBGINP 


¢ Debug interactively by entering debugging commands from your work station 


¢ Use a combination of the above two methods 


SERVICE Debugging Commands 


The commands that you can use to debug the compiler are shown in the following 
table, and described in the text below. 


You can specify these commands either from your terminal, from source file 
member QPLIDBGINP, or from either place, as shown below: 


Command Use from Use from 
QPLIDBGINP | Work Station 
Ce 5 


TERMINATE or Yes Yes 
TER 


NODEBUG or Yes Yes 
NOD 
EXECUTE or Yes Yes 
EXE 
NOEXECUTE or | Yes Yes 
NOE 


Figure A-8 (Part 1 of 2). Commands to use with the SERVICE parameter 
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Command Use from Use from 
a Work Station 


CON 


SEGMENT or 
SEG 


Figure A-8 (Part 2 of 2). Commands to use with the SERVICE parameter 


The command syntax and descriptions follow: 


* 


Use in file QPLIDBGINP to indicate that text following the asterisk is treated 
as comments. 


p>—INSERT formatte AFTER phase——____»> 
= 


The formatter will follow or precede the phase. 
Formatters and phases must be abbreviated to three characters as follows: 
1. Drop the first three characters of the phase name (QPC). 
2. Retain the fourth and fifth characters of the phase name. 
3. Drop the first two digits (00) of the three digit number. 
4. Retain the last digit. 


For example, the formatter QPCPF008 must be abbreviated as PF8, and the 
phase QPCLP001 must be abbreviated as LP1. 


The following table lists the places where you can use a formatter, and the type 
of intermediate text that is formatted and listed. 


Note: ZZ1 is a phase, but it also acts as a formatter. 


A-16 PL/I User's Guide and Reference 


COMPILER DEBUGGING OPTIONS 


Formatter one 


AFTER 


BEFORE | any 
AFTER 


N-Address- 1 
N-Address- 1 
N-Address- 1 
N-Address- 1 
N-Address- 1 
N-Address- 1 
N-Address- 1 
N-Address- 1 
FIT 

EFIT 

EFIT 


Polish-2 
Polish-2 
Polish-2 
N-Address-2 
N-Address-2 
N-Address-2 
N-Address-2 


Figure A-9 (Part 1 of 2). Using the INSERT Command 
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Formatter | BEFORE 


Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary J 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
Dictionary 
a 


Constant string 
Constant string Jd 
Constant string 
Constant string 
Constant string 
Constant string 
Constant string 
Constant string 
Constant string 
Constant string 


Figure A-9 (Part 2 of 2). Using the INSERT Command J 


The first time you call ZZ1, (by specifying SERVICE (*YES) on the 
CRTPLIPGM command), source file member QPLIDBGINP is processed, if it 
exists. If you call ZZ 1 again, (either from QPLIDBGINP or interactively from 
your work station), you may only process commands from your work station. 
Therefore, if you call ZZ1 from QPLIDBGINP, processing is temporarily 
halted to enable you to enter any debugging commands from your work station. 


p>—INSERT formatter AFTER phase-——————_»> 
[= 
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processes the normal ending of compilation following or preceding the specified 
phase. Phase TM1 is called. 


DEBUG phase 
This puts you in debug mode (the equivalent of issuing the STRDBG cL 
command), with a breakpoint at the beginning of the program. For information 
about using debug mode, refer to Programming: Control Language Program- 
mer’s Guide. 


NODEBUG phase 
If you have previously specified DEBUG for a phase, you can now specify that 
you do not want to enter debug mode for that phase. 


NOEXECUTE phase 
The phase specified will not be processed. 


EXECUTE phase 
If you have previously specified NOEXECUTE for a phase, you can now 
specify that the phase be processed. 


CONSOLE 
Specifies, from source file member QPLIDBGINP, that commands may be 
entered from the work station. 


SEGMENT segment-identifier 
produces a dump of the named segment-identifier. Segment-identifier is a 
number from | through 19. 


In interactive mode, a help text screen shows the syntax and definitions of the 
above commands. 


Quantitative Limits of Compiler 


The following table gives information about the maxima, minima, and defaults of 
the AS/400 PL/I compiler. 


General 


Collating sequence 
Digits in exponent of floating-point variable 
Length of string returned by TIME 


Maxima 


%INCLUDE — number of members 
%SKIP — number of lines 
A,B,B1,B4,X,COL 

Arguments for MAX/MIN built-in functions 
Arguments in a CALL statement 

Arguments in a function reference 

BINARY FIXED precision 


EBCDIC 
3 
9 
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Maxima 


Blocks in an external procedure 
DECIMAL FIXED precision 
Depths of nesting 
“INCLUDE source file 
Attribute factorization 
Comments 
Combined nesting depth (see glossary) 
DO in GET and PUT statements 
Do-groups 
Functions 
IF... THEN...ELSE statements 
INITIAL attribute iterations 
Procedures and begin-blocks 
SELECT statements 
Structures 
Dimensions of an array 
Exponent in BINARY FLOAT variables 
Short form 
Long form 
Exponent in DECIMAL FLOAT variables 
Short form 
Long form 
Extent of an array 
INITIAL attribute iteration factor 
Keylength (composite key) 
Labels per single statement 
Length of array 
Length of BIT string 
Length of CHARACTER VARYING data item 
Length of fully qualified name 
(excluding periods) 
Length of title 
Length of programmer-defined name 
Length of programmer-defined AS/400 name 
Length of statement 
Level number in structure 
LINE expression 
Linesize — record format F 
Names defined by programmer 
if all names are 31 characters long 
if all names are 10 characters long 
On-units in a block 
Pagesize 
Parameters in a procedure 
PICTURE format specification — length 
PICTURE — number of digits in specification 
Record size — record format F 
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255 


38 approximately 

308 approximately 

32 767 

32 767 

120 

1 

4194303 bytes 

32 767 bits 

32 765 characters 

15 structures (levels) * 31 characters 


33 characters 
31 characters 
10 characters 
32 767 characters 


255 characters 
15 
32 767 characters 


Maxima 


Significand of BINARY FLOAT variable 
Short form 
Long form 

Significand of DECIMAL FLOAT variable 
Short form 
Long form 

SKIP expression 

Source records 

Statements in a program 

Substatements in a statement 


Minima 

Array extent 

KEYDISP integer constant 
Length of bit or character string 
Linesize — record format F 
PAGESIZE expression 

Relative record number 

Scale factor for FIXED variables 
SKIP expression 

%SKIP — number of lines 


Defaults 
%SKIP — number of lines 
BIT string length 


CHARACTER string length 

FIXED BINARY precision and scale 
FIXED DECIMAL precision and scale 
FLOAT DECIMAL precision 

FLOAT BINARY precision 

LINE 

PAGESIZE 

PRINT file format 

SKIP expression 
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24 binary digits 
53 binary digits 


7 decimal digits 
16 decimal digits 
32 767 

99999 

9999 

9999 


== Oe SS SS OO. 
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Appendix B. The AS/400 PL/I Language Summary and 


Character Set 


The AS/400 PL/I compiler was designed to conform to the General-Purpose Subset 
(Subset G) of PL/I as defined by the American National Standards Institute (ANsI). 


The following table compares the language features of AS/400 PL/I to the ANSI 
Subset G standard. The table shows only how AS/400 PL/I deviates from Subset G. 


Following the table is a listing of the PL/I character set. 


For details about specific language features, refer to the appropriate section in this 


manual. 


blank 


Key: 


The AS/400 implementation is the same as defined by ANsI Subset 
G. 


The AS/400 implementation offers additional function above ANSI 
Subset G. 


The AS/400 implementation has restrictions below what is defined 
by ANSI Subset G. 


The AS/400 implementation does not support this ANSI Subset G 
language feature. 


This language feature is implementation defined (in conformance 
with ANSI Subset G). 


This language feature is not in Subset G. 


For features where A or blank appear under the Subset G column, 
indicates the source that the AS/400 PL/I feature was modelled after: 


e the feature is part of the full ANSI PL/I language, but is not in 
Subset G. 


¢ the feature is a language extension that also exists in other IBM 
PL/I compilers. 


e the feature is a language extension that exists only in the 
AS/400 PL/I compiler. 
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LANGUAGE oo Full IBM AS/400 
FEATURE ANSI | Extension Extension 


a 


Assignment 
BY NAME 


scalar to 
connected structure 


a 


a 


DECLARE 
(see Attributes) 
factored attributes 
nested factoring 
declaration of SYSIN 
and SYSPRINT assumed 


DELETE 
KEY 
OPTIONS 


DO iterate 
control variable 


STRING 
format items 


B2/B3 
P ‘picture! 


[coroercoro i= |) 


IF A 
THEN/ELSE unit labeled S 


ZZALZLZAPA 
=f 
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LANGUAGE ania Full IBM AS/400 
FEATURE ANSI | Extension Extension 


erate Ps 


SYSTEM 


DIRECT 
ENVIRONMENT 
KEYED 

PRINT 

RECORD 

SEQUENTIAL 

STREAM 

TAB 

TITLE 

other than character string 


PUT 
FILE 
LIST 
STRING 
format items 
B2/B3 
P 'picture' 
TAB(n) 


READ 
KEY 
KEYTO 
OPTIONS 


RETURN 
| descriptor 
| FILE 


REWRITE 
KEY 
OPTIONS 


En 
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LANGUAGE ae Full | IBM AS/400 
FEATURE ANSI | Extension Extension 
SIGNAL a as en 


| WRITE 
KEYFROM 
OPTIONS 


Directives 


LANGUAGE a Full IBM AS/400 
FEATURE ANSI | Extension Extension 


INCLUDE Ea 


Ce 
sce SS—~dCSSidE Cs 


Label Prefixes 


2 rr 
FEATURE ANSI | Extension Extension 
romat Jw 

Trocepure———S—id= | | i 

renee wi ~~ is sid 

WHENOTHERWISEw [|| +s 

fotternatenests =| |i 

fing bet ony [= |} | 

[ubeciped ately —[N [| <i 
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Conditions 


LANGUAGE Subset| Full IBM AS/400 
FEATURE ANSI | Extension Extension 


on units 
FIXEDOVERFLOW 
OVERFLOW 
TRANSMIT 
UNDERFLOW 
ZERODIVIDE 


default enablement 
RECORD 
STORAGE 
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LANGUAGE Subset} Full | IBM AS/400 
FEATURE G ANSI | Extension Extension 
Se ee ee 


Acos 
ADDR | 
ASIN 
ATAN Gy) T= 
ATAND Gly) =P 
ATANH 
BINARY, t= 
prrwiiy 
oo IN 
a ES ee 
(CHARACTER Wh) T= fT 
couaTe IN 


pecmal ———SSC~i 
pimension i= | | 


uencta ———SS—~—~i PP 
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LANGUAGE Subset} Full | IBM AS/400 
FEATURE G ANSI | Extension Extension 


LINENO 


foxcope——SS—~d SP 
Cn 
foxceySSC—~—~s 
En 
Purery SSS dS 
Pusnuron «dS dS 
RowD——S—~wd= Pd 
saMEKEY Sid) 
sion SS— 
Ea 
EO 
Ea 
sort SSOS—S 
[storage ——SS«dSidE SS 
srancSS—iN 
suasTe ea «d= | | i 
TaN 


TRANSLATE (lt) T= TP 
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FEATURE ANSI | Extension Extension 

rune 
funsrecSSC*id PO 
va SSN Td 
oT 


Built-in Subroutines 


[Builtsin Subroutines 
FEATURE ANSI | Extension Extension 
Pucomt 
upume SiS 
Puiorp SiS 
muiopNrpa——SS*dY SS 
Purcvusa «dP | | 
Puerco SSS SO 
frunouusack «dE dS 


Pseudovariables 


LANGUAGE aa Full IBM AS/400 
FEATURE ANSI | Extension Extension 
PAGENO a a 

SUBSTR (sil) ae ak a oa 
UNSPEC ee 
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LANGUAGE Subset} Full IBM AS/400 
FEATURE G ANSI | Extension Extension 
ALIGNED R 

BIT R 

ALIGNED attribute optional | N 


AUTOMATIC 
length/dimension 
reference 
subscripted 
pointer qualified 
expression 


BASED 

length/dimension 
reference 

expression 


ZAAAIAZALAAA 


ZALZLZAAR 


constant 
bit 
B2/B3 
constant dimension array 
DECIMAL to 
reference 
subscripted 
pointer qualified 


expression 


Fc 
FORMAT 

dimension 
lower bound not = 1 ie 


[cHaracter [= |) | 
LABEL 
lower/upper bound: 

rect Sid = | dP 


ZAAAZAAAR 
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LANGUAGE Subset] Full IBM AS/400 
FEATURE G ANSI | Extension Extension 


ENTRY A 
descriptor A 
asterisk S 
shortened argument list S 
ENVIRONMENT ie as Ss Gea 
EXTERNAL R 
identifier declared more 
than once in external procedure 
FILE 
variable/parameter 


er 


INITIAL R 
reference R 
(only NULL built-in) 
iteration factor R 
with inherited dimensions N 


reference 
subscripted 
pointer qualified 

expression 


member 
length/dimension 
reference 


ZAAA|AZLZLZAAR 


expression 


fnonsvarng i= || id 
fornons Sis 
fourrer—SSS—~s =P 
Ea a 


PICTURE 
R character 
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LANGUAGE ia t]| Full IBM AS/400 
FEATURE ANSI | Extension Extension 


ponte 


RETURNS 
descriptor 
FILE 


sequent = 
stac—SSS—id 
steam Sid | 
a 


UNALIGNED 
allowed for fixed binary 
and binary/decimal float 


wariasie———S—~d= | d| Cid 
varvinc——=dt= |i) 


Appendix B. The AS/400 PL/I Language Summary and Character Set B-11 


LANGUAGE ee Full IBM AS/400 
FEATURE ANSI | Extension Extension 
Ea 


subscripted 
interleaved sae 


PRN (Ce A Sa 


Character Set 


LANGUAGE ad Full IBM AS/400 
FEATURE ANSI | Extension Extension 
aaa <a le SNIONE 


Ee ee OC 
letters $, #, @ a ee ee eee 


digits 0 - 9 


alngal characte a 


B-12 PL/I User’s Guide and Reference 


fAbbreviatios sss 


FEATURE ANSI eaten ae 
ART < Arran > 
ricer ee AS a A 
[auto <automaric> [=| | «| 
BFR <BEFORE> | [| iS 
we einary> [=| | +d 
[onaR < cuaracrer> [=| [<i 
[cor <couumn> ‘t= | |i 
Der <pectare> f= || sd 
[pec < pecimat> [=] | id 
[DIM < only fomatowe> [=| |_| 
feNy < ENvinonMENT> [=| [| 
equ <nqua> —+| | | dS 
fexr <exterNac> [= || +i 
[FOr < Fixepoverriow>[N [|| 
ierenmat> [=| |i 
int <interNac> [=| |i 
Itenexr> iP dS 
fort < overruow> [N | [+i 
[OTHER < OTHERWSES | [|S _-| 
mic <ricrors> [= | |i 
[PROC < proceDuRE> [= || + 
[pv <previous> | | | «dS 
[pre <ronter> [= || +i 
[seQr < sequential > [= || —+| 
[s1G <storaGe> | | [s+ 
[ur = UNDERFLOw> [N | | sd 
[UNAL < UNaLIGNED> [= [| +. 
[UNDE < uNpEFINEDRLE> [=| | +d 
VAR <VARIABLE> [= [| 
zp <zeropiipe > |N_ | | | 
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PL/I CHARACTER SET 


The PL/I Character Set 


The language characters are alphabetic characters, digits, and special characters. 


There are 29 alphabetic characters: 


Character Meaning 


A-Z English alphabet 


| IBM Extension | 


$ currency symbol 
# number sign 
@ commercial “at” sign 


fe End of IBM Extension _ 


There are ten digits: 0 through 9. 


There are 20 special characters: 


Character Name 


blank 

equal sign or assignment symbol 
plus 

minus 

asterisk or multiplication 

slash or division 

left parenthesis 

right parenthesis 

comma 

point or period 

: apostrophe 

% percent 

: semicolon 

: colon 

“7 not 
& and 
| 
> 
< 


a een ea | 


or 
greater than 
less than 

break character 


You can combine certain special characters to create the following ten composite 
symbols: 
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Name 


less than or equal to 
concatenation 
exponentiation 

not less than 

not greater than 

not equal to 

greater than or equal to 
begin comment 

end comment 

points to 


EBCDIC Codes 


CC The language characters, with their EBCDIC codes represented in hexadecimal nota- 
tion can be found in Appendix E, “EBCDIC CODES.” 


The EBCDIC codes may be represented by different characters on different terminals 


or printers. 


Lowercase Characters 


a character literal, the lowercase character maintains its identity as lowercase. In 


( You can use lowercase characters when writing a source program. In a comment or 


other uses (such as keywords or names), the lowercase character is equivalent to its 
corresponding uppercase character. 


Extralingual Characters 


Character constants and comments can contain any of the 256 EBCDIC codes. Any 
character that is not a language character is an extralingual character. 
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PL/I CHARACTER SET 
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Appendix C. Valid Combinations of Options for Input/Output 
Statements 


The tables in this appendix show the combinations of options you can use in input 
and output statements. The following abbreviations are used in the table headings: 


I Input 
O Output 
U Update 


In the body of the tables, the following set of symbols is used: 


R Required 
O Optional 
= Not valid 


Footnotes for all the tables are at the end of the appendix. 


The following should be noted: 
¢ Options that are not valid either produce an error or are ignored. 


e You cannot specify the OPTIONS option in your input/output statements if 
you specify the ENVIRONMENT option BLOCK in your file declaration. 


¢ Ifa statement is not listed for a particular file type, it cannot be used for that file 
type. 


¢ Some input/output options that are listed as being invalid for certain file types 
will not produce error messages at compile time, but when running is attempted 
the statement will fail. The reason for this is that at compile time it is not 
known what AS/400 file type the file declared will be attached to. 


Appendix C. Valid Combinations of Options for Input/Output Statements C-1 


Data Base Files with CONSECUTIVE organization 


FILE ACCESS 


SEQUENTIAL SEQUENTIAL DIRECT 
KEYED 


pot of et tf of uf at} of 


READ 
FILE 
INTO | SET 


OPTIONS 
RECORDIS 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


WRITE 
FILE 
FROM 
KEYFROM 
OPTIONS 
RECORD!)5 
INDICATORS 


REWRITE 
FILE 
FROM 
KEY 
OPTIONS 
RECORDS 
INDICATORS 


DELETE 
FILE 
KEY 
OPTIONS 
RECORDI5 


"OO0ORAR 
"OOARRR 


OCOOOR 
OCOOAR 
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C Data Base Files with INDEXED organization 


FILE ACCESS 


SEQUENTIAL SEQUENTIAL DIRECT 
KEYED 


READ 

FILE 

INTO | SET 

KEY 

KEYTO 

OPTIONS 

Cc RECORD 
KEYSEARCH 

POSITION 

NBRKEYFLDS 

INDICATORS 

MODIFIED 


WRITE 
FILE 
FROM 
KEYFROM 
C OPTIONS 
RECORD 
INDICATORS 


REWRITE 
FILE 
FROM 
KEY 
OPTIONS 


‘ RECORD 
INDICATORS 

DELETE 

FILE 

KEY 


OPTIONS 
RECORD 


Aw 
"O' 000* BARB 


t O oO t 


"OOORR 
"OORA AR 


O0O0On 
COA R 
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Display Files with INTERACTIVE organization 


SEQUENTIAL 
ACCESS 


READ 
FILE 
INTO | SET 


KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


INDICATORS 
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Cc Subfiles with INTERACTIVE organization 


SEQUENTIAL 
KEYED ACCESS 


READ 
FILE 
INTO | SET 
KEY 

KEYTO 
OPTIONS 
RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


WRITE 
FILE 
FROM 
KEYFROM 
OPTIONS 

RECORD 

INDICATORS 


REWRITE 
FILE 
FROM 
KEYFROM 
OPTIONS 

RECORD 

INDICATORS 
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Display Files with CONSECUTIVE organization 


FILE ACCESS 


SEQUENTIAL SEQUENTIAL 


OPTIONS 
RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


WRITE 
FILE 
FROM 
KEYFROM 
OPTIONS 

RECORD 

INDICATORS 


Note: Use CONSECUTIVE organization only for simple input and output. If the 
user is entering input and you are supplying prompt screens, or if you are providing 
output but allowing the user to direct program processing, for example by entering 
record keys, you must use INTERACTIVE organization. 
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(C Inline Files with CONSECUTIVE organization 


SEQUENTIAL 
ACCESS 


READ 
FILE 
INTO | SET 
KEY 
KEYTO 
OPTIONS 
RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


SEQUENTIAL 
ACCESS 


INDICATORS 
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Tape and Diskette Files with CONSECUTIVE organization 


SEQUENTIAL 
ACCESS 


INTO | SET 
KEY 
KEYTO 
OPTIONS 
RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


WRITE 
FILE 
FROM 
KEYFROM 
OPTIONS 

RECORD 

INDICATORS 
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Communications and BSC Files with INTERACTIVE and CONSECUTIVE 
Organization 


SEQUENTIAL ACCESS 
CONSECUTIVE INTERACTIVE 


READ 
FILE 
INTO | SET 
KEY 
KEYTO 
OPTIONS 
RECORD 
KEYSEARCH 
POSITION 
NBRKEYFLDS 
INDICATORS 
MODIFIED 


WRITE 
FILE 
FROM 
KEYFROM 


OPTIONS 
RECORD 
INDICATORS 


Appendix C. Valid Combinations of Options for Input/Output Statements C-9 


Footnotes: 


1. 


NH On FF WH WNW 


The file must contain external record definitions and must have the DDs 
INDARA keyword specified. The ENVIRONMENT option NOINDARA 
must not be specified. 


. The KEY and KEYTO options are mutually exclusive. 

. Only POSITION option NEXT allowed. 

. KEYSEARCH is not allowed if KEY is not specified. 

. POSITION may not be specified with KEY. 

. The KEYFROM(*) option is not allowed. 

. KEYFROM(expression) may only be used if the ENVIRONMENT options 


KEYDISP and KEYLENGTH are specified. If the ENVIRONMENT option 
DESCRIBED 1s specified, you must specify KEYFROM(*). 


. Must have the pps INZRCD keyword specified. 
. KEYFROM may not be specified when writing to a subfile control record 


format. 


. MODIFIED may not be specified with KEY. 
. The RECORD option must be used with files that contain external record defi- 


nitions. 


. POSITION options NXTUNQ, PRVUNQ, NXTEQL, and PRVEQL are not 


allowed. 


. INDICATORS may not be specified with POSITION. 
. NBRKEYFLDS is not allowed if POSITION 


(NEXT|PREVIOUS|FIRST|LAST) is specified. 


. The file must contain external record definitions (DDs described). 
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CONDITIONS 


Ae Appendix D. Conditions and Condition Codes 


Conditions 


This section presents conditions in alphabetical order. In general, the following 
information is given for each condition: 


¢ Description: A discussion of the condition, including the circumstances under 
which the condition may be raised. 


¢ Implicit action: The action taken when a condition is raised and no on-unit is 
currently established for that condition. In most cases, a message is issued. 


Cc ¢ Normal return: The point to which control returns if the on-unit ends normally; 

that is, when it is not left by a GO TO statement or ended by a STOP state- 
ment. If a condition other than ERROR has been raised by the SIGNAL 
statement, the normal return is always to the statement immediately following 
SIGNAL. 


The condition codes that correspond to the different situations in which a condition 

is raised are the values returned by the ONCODE built-in function. The condition 

codes for each condition, their meanings, and any 0S/400 or PL/I messages associated 
Cc with the condition follow this list. 


If a message is issued for a condition, it will be directed to the program message 
queue of the run-unit’s initial PL/I procedure. In addition to the message text, the 
message will contain the condition code, the program statement number, and the 
name of the external procedure containing the statement that raised the condition. 
In certain cases, the message will also contain the name of the file that caused the 
condition, the value of the key, or other information pertinent to the condition 
raised. 


[ The following conditions, shown in uppercase, may be specified in an ON or 
SIGNAL statement: 


ENDFILE KEY 
ENDPAGE TRANSMIT 
ERROR UNDEFINEDFILE 


The following conditions, shown in lowercase, cannot be specified in an ON or 
SIGNAL statement: 
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CONDITIONS 


Conversion Storage 
Fixedoverflow Stringsize 
Overflow Underflow 
Record Zerodivide 


All the conditions are described in the following sections in alphabetical order. 


Conversion Condition 
This condition cannot be written in an ON or SIGNAL statement. 


Description: The conversion condition is raised when an invalid conversion is 
attempted. 


Implicit Action: A message is issued and the ERROR condition 1s raised. 


Normal Return: The ERROR on-unit must not return normally. 


ENDFILE Condition 


Description: The ENDFILE condition is raised during a GET or READ operation 
by an attempt to read past the end of a file. 


In record data transmission, ENDFILE is raised whenever the end of a file is found 
while processing a READ statement. 


In stream data transmission, ENDFILE 1s raised while processing a GET statement 
if the end of a file is found before any items in the GET statement’s data list have 
been transmitted, between transmission of two of the data items, or within a SKIP 
option. If the end of a file is found within a data item, or while an X-format item is 
being executed, the ERROR condition is raised. 


If the file is not closed after ENDFILE has been raised, any subsequent GET state- 
ment, or READ statement in the same direction for that file will again raise the 
ENDFILE condition. 


Implicit Action: A message is issued and the ERROR condition is raised. 


Normal Return: Processing continues with the statement immediately following the 
GET or READ statement that raised the ENDFILE condition. 


ENDPAGE Condition 


Description: The ENDPAGE condition is raised for stream files when the last line 
has been printed on a page or if a LINE option or format item specifies a line 
number lower than the current line number. For record files, a TRANSMIT condi- 
tion is raised. You can specify the number of lines for a page in the PAGESIZE 
option in an OPEN statement. If you do not specify PAGESIZE, a default limit of 
60 is applied. The attempt to exceed the limit may be made during data trans- 
mission (including associated format items) or by the LINE or SKIP option. 
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CONDITIONS 


ENDPAGE is raised only once for each page unless it is raised by the SIGNAL 
statement. 


When ENDPAGE is raised, the current line number is | greater than the page size; 
it is therefore possible to continue writing on the same page. The on-unit may start 
a new page by processing a PAGE option or a PAGE format item, which sets the 
current line to 1. 


If the on-unit does not start a new page, the current line number may increase indef- 
initely. Any subsequent LINE option or LINE format item starts a new page and 
sets the current line number to | without raising ENDPAGE, unless the current line 
number is equal to the specified line number and the file is positioned on column 1 
of the line. In this case, the LINE specification is ignored, ENDPAGE is not 
raised, and no new page is started. 


If ENDPAGE is raised during data transmission, the remaining data is written on 
the current line on return from the on-unit; the line number may have been changed 
by the on-unit. 


If ENDPAGE results from a LINE or SKIP option or format item, then, on return 
from the on-unit, the action specified by LINE or SKIP is ignored. 


Implicit Action: A new page is started and processing of the PUT statement con- 
tinues. 


Normal Return: Processing of the PUT statement continues. 


ERROR Condition 


Description: The ERROR condition is raised by: 


¢ The implicit action for a condition for which that action is to issue an error 
message and raise the ERROR condition, such as the implicit action for the 
UNDEFINEDFILE condition. 


e An error for which there is no other condition. This error may be a hardware 
detected error, such as an address exception, or a software detected error, such 
as processing an input/output statement for a file while another input/output 
statement is processing for the same file. 

Implicit Action: The program ends abnormally. If the ERROR condition was 
raised because of an error for which no other condition exists (second case above), a 
message is issued before ending. 


Normal Return: The program ends abnormally. 


Fixedoverflow Condition 


This condition cannot be written in an ON or SIGNAL statement. 
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CONDITIONS 


Description: The fixedoverflow condition is raised when the number of digits of the J 
intermediate result of a fixed-point arithmetic operation exceeds the maximum 

number of digits allowed by the implementation. The maximum for intermediate 

results is at least 15 for decimal fixed-point values and at least 31 for binary fixed- 

point values. 

The fixedoverflow condition is also raised when high-order significant digits are lost 

in an attempted assignment to a variable or in an input/output operation. This loss 

may result from a conversion involving different data types, different bases, different 

scales, or different precisions. 

Implicit Action: A message is issued and the ERROR condition is raised. 


Normal Return: The ERROR on-unit must not return normally. 


KEY Condition JZ 


Description: The KEY condition can be raised only during operations on keyed 
records. For the possible causes of the KEY condition, see Figure D-1 on 

page D-6. 

Implicit Action: A message is issued and the ERROR condition is raised. 


Normal Return: Control passes to the statement immediately following the state- 
ment that caused KEY to be raised. ) 


Overflow Condition 
This condition cannot be written in an ON or SIGNAL statement. 


Description: The overflow condition is raised when the magnitude of a floating- 
point number exceeds the permitted maximum. No value is stored in the target. 


Implicit Action: A message is issued and the ERROR condition is raised. ) 


Normal Return: The ERROR on-unit must not return normally. 


Record Condition 

This condition cannot be written in an ON or SIGNAL statement. 

Description: The record input/output condition can be raised only during a 
READ, WRITE, or REWRITE operation. For the possible causes of the condi- 
tion, see Figure D-1 on page D-6. 


Implicit Action: A message is issued and the ERROR condition is raised. 


Normal Return: The ERROR on-unit must not return normally. 
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CONDITIONS 


Storage Condition 
This condition cannot be written in an ON or SIGNAL statement. 


Description: The storage condition is raised when an ALLOCATE statement is 
processed without enough storage available for the request. 


Implicit Action: A message is issued and the ERROR condition is raised. 


Normal return: The ERROR on-unit must not return normally. 


Stringsize Condition 

This condition cannot be written in an ON or SIGNAL statement. 

Description: The stringsize condition is raised when a string is assigned to a shorter 
target. If the condition is detected by a PL/I run-time routine and you specified 
GENOPT(*DIAGNOSE) in the CRTPLIPGM command when you compiled the 


program, an informational message is issued. 


Implicit Action: The string is truncated to the right and processing continues. 


| Full Language Extension | 


TRANSMIT Condition 


Description: The TRANSMIT input/output condition can be raised during any 
input or output operation in which the record is not transmitted. 


Implicit Action: A message is issued and the ERROR condition is raised. 


Normal Return: Processing continues with the statement immediately following the 
input or output statement that raised the condition. 


[End of Full Language Extension _ 


UNDEFINEDFILE Condition 


Description: The UNDEFINEDFILE condition is raised by an unsuccessful 
attempt to open a file. 


If UNDEFINEDFILE is raised by an implicit opening in an input/output state- 
ment, then, upon normal return from the on-unit, processing continues with the rest 
of the input/output statement, provided that the file has been opened in the on-unit. 
If the file has not been opened, the ERROR condition is raised. 


Implicit Action: A message is issued and the ERROR condition is raised. 
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CONDITION CODES 


Normal Return: Upon the normal completion of the on-unit, control passes to the 
statement immediately following the statement that raised the condition. (See 
“Description” for the action in the case of an implicit opening.) 


Underflow Condition 

This condition cannot be written in an ON or SIGNAL statement. 

Description: The underflow condition is raised when the magnitude of a nonzero 
floating-point number is smaller than the permitted minimum. (UNDERFLOW is 


not raised when equal numbers are subtracted.) 


Implicit Action: A message is issued and processing continues with a value of zero. 


Zerodivide Condition 
This condition cannot be written in an ON or SIGNAL statement. 


Description: The zerodivide condition is raised when an attempt is made to divide 
by zero. 


Implicit Action: A message is issued and the ERROR condition is raised. 


Normal Return: The ERROR on-unit must not return normally. 


Condition Codes 


The following table is a listing of the conditions that can be raised during the 
processing of a program. Each entry contains the condition code, an explanation of 
the error which raised the condition, the condition’s origin, and the PL/I message 
issued. Conditions that can be specified are shown in uppercase; those that cannot 
be specified are shown in lowercase. 
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CONDITION CODES 


'S Condition and PL/I 
codes Meaning Message 


Conversion 
604 Error while processing an PLIO504 
F-format item for a GET 
statement: an exponent was 
found in the character 
value. 


Error while converting from PLIO512 
character to arithmetic. 


Error while converting from PLIOS15 
character to bit. 


C Error while converting from PLI0529 


picture to coded arithmetic: the 
character value of the picture 
does not correspond to its 


specification. 
ENDFILE 
70 A SIGNAL ENDFILE statement was PLI3200 
processed. 
C 7 An end of file was detected. CpFs001, | PLI3201 


CPF5025 


ENDPAGE 
90 A SIGNAL ENDPAGE statement PLI3300 
was processed. 


An end of page was detected. 


91 PLI3301 
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CONDITION CODES 


Condition and PL/I 
codes Meaning Message 


A SIGNAL ERROR statement was PLIO200 
processed. 


Attempt to use SKIP PLI1704 
< 0 for a print file or 
< 0 for non-print file. 


A REWRITE or a DELETE statement | CPF5011, | PLI1707 
was not preceded by a READ CPF5147 
statement on a sequential file. 


Attempt to process a DELETE 
for a sequentially accessed 

file under commitment control 
after a commit or rollback 

is done. (A commit or a 
rollback releases all record 
locks.) This is caused by a 
logic error in the user 

program. ‘The record is not 
deleted. 


Attempt to process a REWRITE 
for a sequentially accessed 

file under commitment control 
after a commit or rollback is 
done. (A commit or a rollback 
releases all record locks.) 

This is caused by a logic 

error in the user program. 

The record is not deleted. 


An input/output statement PLI1709 
specifies an operation or an 

option that conflicts with 

the file. 


A REWRITE or DELETE was PLI1710 
attempted using an invalid 
record format. 
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CONDITION CODES 


‘SG Condition and PL/I 
codes Meaning Message 


Data management has detected an CPF4500, | PLI1711 
input/output error. CPF4600, 
Use PLIRCVMSG for more CPF5100, 
information unless the CPF5200, 
originating message was CPF5300, 
a STATUS type message. CPF5500, 

CPF5600 


After the UNDEFINEDFILE PL/I PLI1716 
condition was raised as a result 
of an unsuccessful attempt to 
|S implicitly open a file, the file 
was found unopened on 
normal return from the on-unit. 


End of file was found PLI1718 
while processing a data item 
or X-format item. 


Argument passed to built-in MCHS003_ | PLI1801 
function is invalid (for 


example, out of range). 


The *DIAGNOSE option was MCH0603 | PLIO909 
selected when the program was 

compiled. Therefore MI string 

constrainment was specified 

when the program was created. 

A violation has occurred and 

MCH0603 exception was signalled. 


C Attempt to free a variable PLI2151 
that has no valid allocation. 
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CONDITION CODES 


Condition and PL/I J 
codes Meaning Message 


When an ALLOCATE or FREE PLI2159 
statement was being processed, 
an element of the free area 
| chain was found that did not 
contain valid information. 


The number of arguments passed MCH0801 | PLI2200 
to a procedure did not match 

the number of parameters 

expected. 


A floating-point operation MCH1209 | PLI1900 J 
had invalid operands. 


Address exception. MCH3601 | PLI1905 


Alignment error. MCH0602 | PLI1906 


Function check or other serious CPF9999 PLI2000 
error during processing. or any of 


several | 
MCH . 
messages 

Attempt to process a GO TO PL/I PLI2002 


statement which references an 
invalid statement label. 
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CONDITION CODES 


Condition and PL/I 
codes Meaning Message 


Fixedoverflow 
310 The fixedoverflow condition is MCH1210, | PLI0600 

raised when the number of digits PL/I 
of the intermediate result of a 
fixed-point arithmetic operation 
exceeds the maximum number of 
digits allowed by the 
implementation. The maximum for 
intermediate results is at least 
15 for decimal fixed-point 
values and at least 31 for 
binary fixed-point values. 
The fixedoverflow condition is 
also raised when high-order 
significant digits are lost in 
an I/O operation. This loss may 
result from a conversion 
involving different data types, 
different bases, different 
scales, or different precisions. 
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CONDITION CODES 


Condition and PL/I 
codes Meaning Message 
KEY 


50 A SIGNAL KEY statement was PLI3400 
processed. 


CPF5006, 
CPF5020 


The specified key cannot be PLI3401 


found. 


CPF5008, | PLI3402 


CPF5026 


When duplicate keys are not 
allowed, an attempt was made to 
add a keyed record that has the 
same key as a record already in 
the file. 


A WRITE was done to an existing 
relative record number. 


PL/I 


When duplicate keys are not CPF5034 | PLI3403 
allowed, an attempt was made to 
add a keyed record that has the 
same key as a record already in 
another file over which there is 


a common unique keyed index. 


A WRITE or REWRITE was done 
to an existing relative record number. 


A key conversion was attempted on PLI3404 
a CONSECUTIVE or INTERACTIVE 
file. The key is less than 


or equal to 0. 


Key specification is null | PL/I PLI3405 


string. 


An invalid key was detected by 
os/400. The error is described by 
PLIRCVMSG. 


CPF5090 =| PLI3409 


READ statement with the NXTEQL 
or PRVEQL POSITION option was 
used and there was no next or 
previous equal key in the access 

path. 


CPF5006 =| PLI3412 
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CONDITION CODES 


Condition and PL/I 
codes Meaning Message 


Overflow 
300 A floating-point number is greater than | MCH1206 | PLIO700 
the maximum size permitted. 


Record 
2] 


The record variable is smaller than the PLI3601 
record size; in a READ INTO state- 


ment the rest of the record is lost. 


The record variable is larger than the 
record size; in a READ INTO state- 
ment the rest of the variable is unde- 
fined. 


The length of the record variable in a 
WRITE or REWRITE statement is 
zero or the variable is too short to 
contain the embedded key. No trans- 
mission occurs. This condition is 
raised only for data base files or device 
files that do not contain DDs. 


PLI3602 


PLI3603 


An ALLOCATE statement requested 
more storage than is available to the 
program. 


MCH2804, 
MCH5401 


PLI0485 


Storage 
8085 
Stringsize 
none 


The stringsize condition is raised when | PL/I PLI1000 


a string is assigned to a shorter target. 
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CONDITION CODES 


Condition and PL/I 
codes Meaning Message 


TRANSMIT 
40 A SIGNAL TRANSMIT statement PLI3700 
was processed. 


43 File input/output error. Use CPF4700, | PLI3703 
PLIRCVMSG for more information, CPF4800, 
unless the originating message CPF5000 
was a STATUS type message. 


Printer overflow line detected. CPF5004 PLI3704 


Record locked. Use PLIRCVMSG CPF5027, | PLI3707 
for more information, unless the CPF5032 

originating message was a STATUS 

type message. 


The requested record is 
currently locked. 


Note: Attempt to process a read 
for a record in a file which is 
opened for UPDATE. The record 
is locked, and remains locked 
until the next file operation is 
processed. The program should 
ensure that any such locks held 

by the program are released. 


Data conversion through CPF5029, | PLI3708 
input/output with a logical CPF5035 
file. 


File size limit exceeded. CPF5018, | PLI3709 
CPF5043 
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CONDITION CODES 


c Condition and PL/I 
codes Meaning Message 


UNDEFINEDFILE 
80 


81 


A SIGNAL UNDEFINEDFILE 
statement was processed. 


The attributes in a DECLARE 
statement conflict with those of 
an explicit or implicit OPEN. 


The file attributes conflict 

with the physical characteristics 
of the AS/400 file, such as a 
conflict between the file 
organization and the device type. 


File or member not found. 


The value of the LINESIZE option 
on the OPEN statement is too 
large for the logical record 

length of the device. 


Authorization failure. 


An error was detected by 0s/400 
while opening a file. Use 
PLIRCVMSG to obtain more 
information, unless the 

Originating message was a STATUS 
type message. 


A file under commitment control 
has been opened, but either the 
STRCMTCTL command has not 
been issued or this file is not 
journaled to the same file as 

the other files under commitment 
control. The file is not 

opened. 
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CPF4101, 
CPF4102 


PL/I 


CPF4104, 
CPF4236 


CPF4100, 
CPF 4200, 
CPF4300 


PLI3800 


| PLI3801 


PLI3802 


PLI3804 


PLI3806 


PLI3809 


PLI3813 
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CONDITION CODES 


Condition and PL/I 
codes Meaning Message 


UNDEFINEDFILE 
(cont) 
96 


97 


98 


Underflow 
none 


Zerodivide 
320 


Invalid TITLE option. 


Unable to allocate objects for 
file. 


Attributes of the currently 


open file do not match the 
attributes specified in the 
OPEN statement. 


A floating-point number is smaller 
than the minimum size permitted. 


A divide operation was attempted 
using zero as the divisor. 
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PL/I 
CPF4128 


PL/I 


MCH1207 


MCH1211, 
MCH1214 


PLI3816 


PLI3817 


PLI3818 


PLI1200 


PLI1300 
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The EBCDIC codes may be represented by different characters on different terminals 


or printers. 
Character EBCDIC Code Character EBCDIC Code 
blank 40 S A2 
; 4B t A3 
< 4C u A4 
( 4D Vv A5 
+ 4E Ww A6 
| 4F x A7 
& 50 y A8 
$ 5B Z A9 
* 5C A Cl 
) 5D B C2 
: SE C C3 
= SF D C4 
- 60 E C5 
/ 61 F C6 
: 6B G C7 
% 6C H C8 
a 6D J C9 
> 6E J D1 
: TA K D2 
# 7B L D3 
@ 7C M D4 
I ID N D5 
= TE O D6 
a 81 P D7 
b 82 Q D8 
c 83 R D9 
d 84 S E2 
e 85 T E3 
f 86 U F4 
h 88 W E6 
i 89 xX E7 
j 91 Y E8 
k 92 Z E9 
l 93 0 FO 
m 94 ] Fl 
n 95 2 F2 
o 96 3 F3 
p 97 4 F4 
q 98 5 F5 
r 99 6 F6 
7 F7 
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Character EBCDIC Code 


8 F8 
9 F9 
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TWO ENVIRONMENTS 


Appendix F. Converting from System/38 to the AS/400 System 


Your Choice of Two Environments: AS/400 System or the System/38 


Environment 


The AS/400 System offers many enhancements over System/38. However, because 
a great many PL/I programs have been written for the System/38 computer, and 
because many programmers are already familiar with the System/38, the AS/400 
System also supports these programs. 


The CL command CALL QCL changes the AS/400 System screen display to appear 
to the user as a System/38. This is known as the System/38 Environment. When 
you are in this environment, you can enter and compile PL/I programs, and do any- 
thing else, as if you were using a System/38 machine. To exit from the System/38 
Environment, you would enter RETURN. To use the System/38 Environment, you 
must have the files QCL and QCMD in your library list. 


Compiling in the System/38 Environment 


You use the CL command CRTPLIPGM to compile PL/I source programs in the 
System/38 Environment just as in the AS/400 System environment. CRTPLIPGM is 
used in a similar manner in the two environments with a few exceptions. They are 
as follows: 

For the PGM parameter the following option applies: 


*CURLIB: If a library name is not specified, the program is stored in *CURLIB. The 
program must not already exist in the library 


For the SRCFILE parameter the following option applies: 
*LIBL: The library list is used to find the source file. 

For the INCFILE parameter the following options applies: 
*LIBL: The library list is used to find the source file. 

For the PRTFILE parameter the following option applies: 
*LIBL:: The library list 1s used to find the print file. 

The PUBAUT parameter is used instead of the AUT parameter. 


For the PUBAUT parameter the following options apply: 
*NORMAL: The program is treated as *CHANGE in the AS/400 System environment. 
*ALL: The public has complete authority for the program. 


Appendix F. Converting from System/38 to the AS/400 System F-1 


TWO ENVIRONMENTS 


*NONE: The program is treated as *EXCLUDE in the AS/400 System environment. 


Examples 


The following command compiles a program named PAYROLL. 
CRTPLIPGM PAYROLL TEXT('Payrol] Program') 


The source program is in the default source file QPLISRC, in a member named 
PAYROLL. A compiler listing is generated. The program runs under the user's 
user profile, and can be run by any system user. 


The following command creates a PL/I program named PARTS. 


CRTPLIPGM PGM(PARTS) + 
SRCFILE(PARTDATA.MYLIB) + 
OPTION(*XREF *OPT) PUBAUT(*NONE) + 
TEXT('This program displays all parts data') 


The program object is stored in the library QGPL. The source program is in the 
PARTS member of the source file PARTDATA in the library MYLIB. A com- 
piler listing, cross-reference listing, and compiler-option list is generated. This 
program, which cannot be used by the public, can be run by the owner or another 
user that the owner has explicitly authorized by name in the CL command 
GRTOBJAUT (Grant Object Authority). 


Writing Programs in the System/38 Environment 
The following % INCLUDE directive and the TITLE parameter of the OPEN state- 
ment show the difference in the filename when using PL/I in the System/38 environ- 
ment. 


Using the “%INCLUDE Directive 
file-name 
An identifier of up to ten characters. The file is located by using the *LIBL 
search list in effect at compile time. The file name cannot begin with a numeric 
and cannot contain periods; the possible characters are A-Z, 0-9, #, @, _. You 
cannot name your file SYSLIB. 


member-name 
An identifier of up to ten characters. The name must be unique within one file. 
The name cannot contain a period or start with a numeric character. 


Using the % INCLUDE Directive for External File Descriptions 
file-name 
An identifier of up to 10 characters. The file is located by using the *LIBL 
search list in effect at compile time. The file name cannot begin with a numeric 
and cannot contains periods; the possible characters are A-Z, 0-9, #, @, _. You 
cannot name your file SYSLIB. 
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Se Syntax of TITLE Parameter of the OPEN Statement 


>>—T I TLE— 2 i e_ vari a 
expression 


where ‘expression! is: 


library_name (member_name) 


title-variable 
( May be any valid program variable whose value is a valid System/38 expression. 
For example: 


ACCOUNTS RECEIVABLE 
= "ACCOUNTS.ACCTLIB(ACCOUNT1) '; 
OPEN FILE (ACCTS) UPDATE 
TITLE (ACCOUNTS RECEIVABLE) ; 


expression 
Must consist of valid System/38 file, library and member name. 


If library-name is omitted, *LIBL is assumed. 


If member-name is omitted, the first member in the file is used. 
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Appendix G. Glossary of Abbreviations 


[Atirention [Stands For ‘([Detnidow 


American An organization sponsored by the Com- 
National Stand- puter and Business Equipment Man- 
ards Institute ufacturers Association for establishing 
voluntary industry standards. 


American 
| National 
Standard Code 
for Information 


The standard code used for information 
interchange between data processing 
systems, data communications systems, 
and associated equipment. The code 
uses a coded character set consisting of 
7-bit coded characters (8 bits including 
parity check). The set consists of control 
characters and graphic characters. 


A form of telecommunication line 
control that uses a standard set of trans- 
mission control characters and control 
character sequences, for binary synchro- 
nous transmission of binary-coded data 
between stations. 


Binary Synchro- 
nous Communi- 
cation 


Operating 
System/400 


The system support licensed program 
for the AS/400 System. It provides 
many functions that are fully integrated 
in the system such as work manage- 
ment, data base data management, job 
control, message handling, security, pro- 
gramming aids, and service. 


OS/400 


Distributed Data 
Management 


A program product that allows an appli- 
cation program or user on a source 
system to access data files on remote 
systems connected by a communications 
network that also uses DDM. 


Data Description 
Specifications 


A description of the user’s data base or 
device files that is entered into the 
system using a fixed-form syntax. The 
description is then used to create files. 
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EBCDIC Extended A coded character set consisting of 8-bit 
Binary-Code coded characters. 


Decimal Inter- 
change Code 


F Function Key A keyboard key that is used to request a 
specific system function. 


FCFC First Character A method for controlling the format of 
Forms Control printed output. The first character of 
gramming; for example, RPG III, CL, 


each record determines the format. 
HLL High-Level Lan- 
guage 
BASIC, and COBOL. 


K. Kilobyte The primary unit of measure for storage 
capacity; 1 K = 1024 bytes. 

NaN Not-A-Number In binary floating-point concepts, a 
value, not interpreted as mathematical 
value, which contains a mask state and 
a sequence of binary digits. 

PL/1 A programming language designed for 
numeric scientific computations, busi- 
ness data processing, systems program- 
ming and other applications. 

QGPL General-Purpose | The library provided by the Control 


Library Program Facility to contain user- 
SDLC 


A programming language that relieves 
the programmer from the ngors of 
machine level or assembler level pro- 


oriented, IBM-provided objects and user- 
created objects not explicitly placed in a 
different library when they are created. 


Synchronous 
Data Link 
Control 


A discipline conforming to subsets of 
the Advanced Data Communication 
Control Procedures (ADDCCP) of the 
American National Standards (ANS) 
and High-level Data Link Control 
(HDLC) of the International Organiza- 
tion for Standardization, for managing 
synchronous, code-transparent, serial- 
by-bit information transfer over a link 
connection. Transmission exchanges 
may be duplex or half-duplex over 
switched or non-switched links. The 
configuration of the link connection 
may be point-to-point, multipoint or 
loop. 
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Source Entry The part of the Utilities Program 
Utility Product used by the operator to enter 
and update source and procedure 

members. 


SEU 


A relational data base management 
system which allows data access in both 
interactive and noninteractive systems. 


Structured Query 
Language 
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additive attribute. A file description attribute that must 
be stated explicitly or implied by another explicitly stated 
attribute. Contrast with alternative attribute. 


allocated variable. A variable to which storage has been 
assigned. 


alternative attribute. A file description attribute that is 
chosen from a group of attributes. Contrast with addi- 
tive attribute. 


arithmetic comparison. A comparison of signed numeric 
values. See also bit comparison, character comparison. 


array. A collection of one or more elements with iden- 
tical attributes, grouped into one or more dimensions. 


array of structures. An array whose elements are struc- 
tures that have identical names, levels, and element attri- 
butes. 


array variable. A variable that represents an aggregate 
of data items that must have identical attributes. Con- 
trast with structure variable. 


assignment statement. A statement that gives a value to 
a variable. It always contains the assignment symbol 


(=). 


based variable. A variable that provides attributes for 
data (such as data located in a buffer) for which the 

storage address is provided by a pointer. It does not 

identify a fixed location in storage. 


begin-block. A block that is activated by error-handling 
on-conditions or through the normal flow of control. 


binary fixed-point value. An integer consisting of binary 
digits and having an optional binary point. Contrast 
with decimal fixed-point value. 


binary floating-point value. An approximation of a real 
number in the form of a significand, which can be con- 
sidered as a binary fraction, and an exponent, which can 
be considered as an integer exponent to the base of 2. 
Contrast with decimal floating-point value. 


bit comparison. A left-to-right, bit-by-bit comparison of 
binary digits. See also arithmetic comparison, character 
comparison. 


bit constant. Either a series of binary digits enclosed in 
apostrophes and followed immediately by B or Bl, or a 


series of hexadecimal digits enclosed in apostrophes and 
followed immediately by B4. Contrast with character 
constant. 


bit value. A sequence of binary digits stored in consec- 
utive bits. 


block. A sequence of statements, processed as a unit, 
that specifies the scope of names and the allocation of 
storage for names declared within it. Contrast with do 


group. 


break character. The underscore symbol (_ ). It can be 
used to improve the readability of identifiers. For 
instance, a variable could be called 
OLD_INVENTORY_TOTAL instead of 
OLDINVENTORYTOTAL. 


built-in function. A predefined function, such as a com- 
monly used arithmetic function or a function necessary 
to language facilities (for example, a function for manip- 
ulating strings or converting data). It is called by a 
built-in function reference. 


built-in function reference. A built-in function name, 
having an optional and possibly empty argument list, 
that represents the value returned by the built-in func- 
tion. 


character comparison. A left-to-right, character-by- 
character comparison according to the collating 
sequence. See also arithmetic comparison, bit compar- 
ison. 


character constant. A sequence of characters enclosed 
in apostrophes; for example, 'CONSTANT'. 


coded arithmetic data. Data items that represent 
numeric values and are characterized by their base 
(decimal or binary), scale (fixed-point or floating-point), 
and precision (the number of digits each can have). 


combined nesting depth. The sum of all 
PROCEDURE/BEGIN/ON, DO, SELECT, and 
IF... THEN...ELSE nestings in the program. 


comparison operator. An operator that can be used in 
an arithmetic, string, or logical relation to indicate the 
comparison to be done between the terms in the 
relation. The comparison operators are = (equal to), 
> (greater than), < (less than), > = (greater than or 
equal to), < = (less than or equal to), . = (not equal 
to), .> (not greater than), — < (not less than). 
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composite symbol. A symbol that consists of more than 


one special character; for example, < =, **, ->, and /*. 


condition. An exceptional situation, either an error 
(such as an overflow), or an expected situation (such as 
the end of an input file). When a condition is raised 
(detected), the action established for it is processed. See 
also established action and implicit action. 


connected aggregate. An array or structure that has no 
inherited dimensions. 


control variable. A variable that is used to control the 
running of a program, as in a DO statement. 


DDM file. A AS/400 file that is associated with a 
remote file that is accessed using DDM. The DDM file 
provides the information needed for a local (source) 
system to locate a remote (target) system and to access 
the file at the target system where the requested data is 
stored. 


data aggregate. A group of data items that can be 
referred to either individually or collectively. There are 
two types of aggregates: arrays and structures. 


data list. In PL/I stream data transmission, a list of the 
data items used in GET EDIT and PUT EDIT state- 
ments. Contrast with format list. 


decimal fixed-point constant. A constant consisting of 
one or more decimal digits with an optional decimal 
point. 


decimal fixed-point value. A rational number consisting 
of a sequence of decimal digits with an assumed position 
of the decimal point. Contrast with binary fixed-point 
value. 


decimal floating-point constant. A value made up of a 
significand that consists of a decimal fixed-point con- 
stant, and an exponent that consists of the letter E fol- 
lowed by an optionally signed integer constant not 
exceeding three digits. 


decimal floating-point value. An approximation of a real 
number, in the form of a significand, which can be con- 
sidered as a decimal fraction, and an exponent, which 
can be considered as an integer exponent to the base of 
10. Contrast with binary floating-point value. 


default. Is used to describe a value, attribute, or option 
that is assumed when none has been specified. 


dimension attribute. An attribute that specifies the 


number of dimensions of an array and indicates the 
bounds of each dimension. 
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directive. A statement that directs the operation of the 
compiler. 


do group. A sequence of statements, processed as a unit, 
that may be a non-iterative do group (processed once or 
possibly not at all) or an iterative do group (processed 
several times, once, or not at all). Contrast with block. 


entry constant. The label prefix of a PROCEDURE 
statement. 


entry data item. A data item that represents an entry 
point to a procedure. 


entry reference. An entry constant, an entry variable 
reference, or a function reference that returns an entry 
value. 


entry variable. A variable to which an entry value can 
be assigned. 


established action. The action taken when a condition is 
raised. See also implicit action and ON-statement 
action. 


explicit declaration. A DECLARE statement that speci- 
fies the attributes of a name. A procedure’s name is 
declared by the PROCEDURE statement: the 
statement’s label is declared as the name of the proce- 
dure. Contrast with implicit declaration. 


expression. A representation of a value; it can consist of 
constants, variables, and function references, along with 
operators or parentheses or both. 


extent. The number of integers between and including 
the lower and upper bounds of an array. 


extralingual character. Any EBCDIC code that is not 
an alphabetic character, a special character, or a digit. 


file constant. A name declared for a file and for which 
a complete set of file description attributes exists during 
the time that the file is open, and with which each file 
must be associated. 


file description attribute. A keyword that describes the 
characteristics of a file. See also alternative attribute 
and additive attribute. 


format list. In PL/I stream data transmission, a list 
specifying the format of the data item on the external 
medimn. Contrast with data list. 


function. A procedure that has a RETURNS option in 
the PROCEDURE statement. A function ends by proc- 
essing a RETURNS (expression) statement and 
returning a scalar value to the point of calling. Contrast 
with subroutine. 


function reference. An entry constant or an entry vari- 
able, either of which must represent a function, followed 
by a possibly empty argument list. Contrast with sub- 
routine reference. 


identifier. A single alphabetic character or a string of 
alphabetic characters, digits, and break characters that 
starts with an alphabetic character. 


implicit. Is used to describe the action taken in the 
absence of an explicit statement. 


implicit action. The action established for a condition 
when the program is activated and that remains estab- 
lished unless overridden by the processing of an ON 
statement for the same condition. Contrast with 
ON-statement action. 


inherited dimensions. For a structure field, those dimen- 
sions that are inherited from the containing structures. 
If the structure field is a scalar variable, the dimensions 
consist entirely of its inherited dimensions. If the struc- 
ture field is an array, its dimensions consist of its inher- 
ited dimensions plus its explicitly declared dimensions. 
A structure field with one or more inherited dimensions 
is referred to as an unconnected aggregate. Contrast 
with connected aggregate. 


initial procedure. An external procedure, called by a 
calling program, that activates a PL/I program. 


instruction pointer. A pointer that provides address- 
ability for an MI instruction in a program. 


integral boundary. The multiple of any 8-bit unit of 
information on which data can be aligned. 


internal procedure. A procedure that is contained in 
another block. Contrast with external procedure. 


keyword. An identifier that when used in a defined 
context takes on a specific meaning, such as an action 
taken or the attributes of data. 


keyword statement. A simple statement that begins with 
a keyword indicating the function of the statement. 


label. An identifier that names a statement so that it can 
be referred to at some other point in the program. 
Sometimes called a label prefix. 


label constant. A name written as the label prefix of any 
statement other than PROCEDURE. Contrast with 
label variable. 


label prefix. See /abel. 


label value. An attribute that identifies a statement in 
the running program. 


label variable. An identifier that contains the label of a 
statement so that the label can be referred to at some 
other point in the program. Contrast with /abel con- 
Stant. 


language character. Any one of the alphabetic charac- 
ters, the digits 0 through 9, and twenty special charac- 
ters. 


level-number. A number that precedes a name in a 
DECLARE statement and specifies the organization of 
the structure in that statement. 


name. Any identifier that the user assigns to a variable 
or to a constant. Sometimes called a user-defined name. 


null statement. A statement that contains only the semi- 
colon symbol (;). 


null string. A character or bit string with a length of 
zero. 


ON-statement action. The action explicitly established 
for a condition when the condition is raised. The 
ON-statement action overrides or suspends any previ- 
ously established action unless it is overridden by a 
further ON-statement for the same condition or until the 
block it was processed in ends. Contrast with implicit 
action. 


operational expression. An expression that consists of 
one or more operations. 


picture data. Arithmetic data represented in character 
form. 


picture specification. A data item that has a numeric 
value but that can also be represented as a character 
value according to the editing characters specified in the 
item's declaration. 


pointer. A type of variable that identifies a location in 
storage. 


pointer value. A value that identifies the location of data 
in storage. 


precision. The number of digits contained in a fixed- 
point data item, or the minimum number of significant 
digits (excluding the exponent) maintained for a floating- 
point data item. 


problem data. Coded arithmetic, bit, character, and 
picture data which represents values processed by the 
program. Contrast with program control data. 


procedure. A block that can be activated from various 
points within a program by use of a CALL statement 
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and can process data passed to it from the block in 
which it was called. See also external procedure and 
internal procedure. 


procedure calling level. The calling level that is incre- 
mented when an internal procedure is called recursively. 
The procedure calling level cannot be specified on 
AS/400 debug commands, and only the last (most 


recent) procedure calling level is available for debugging. 


Contrast with program calling level. 


program contro] data. Pointer, label, entry, and file data 


that is used to control the processing of a PL/I program. 


Contrast with problem data. 


program calling level. The calling level incremented 
when a program or external procedure is called 
recursively. The program calling level can be specified 
on AS/400 debug commands through the INVLVL 
parameter. Contrast with procedure calling level. 


record data transmission. The transmission of data in 
the form of separate records. Contrast with stream data 
transmission. 


recursive procedure. An active procedure that can be 
called from within itself or from within another active 
procedure. 


run unit. A set of PL/I programs, each of which is 
called by some other PL/I program within the set, 
except for the initially called program, which is called 
from outside the set. A PL/I run unit is suspended 
when a program in the run unit calls a non-PL/] 
program, and is resumed when the called program 
returns control to the PL/I program that called it. A 
PL/I run unit is ended when the initially called PL/I 
program returns control to the non-PL/I program that 
originally called the initial program and so started the 
run unit. 


scalar. A type of program object that contains either 
string or numeric data. It provides the byte string it is 
mapped to with representation and operational charac- 
teristics. Contrast with pointer. 
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scalar variable. A variable that represents a single data 
item. 


scope. The part of the program in which a data item 
can be referenced. 


statement. A grouping of identifiers, constants, and 
delimiters that makes up do groups and blocks. The 
end of a statement is indicated by a semicolon (;). See 
also Keyword statement, assignment statement, and null 
Statement. 


stream data transmission. The transmission of data in 
which the organization of the data into records is 
ignored and the data is treated as though it were a con- 
tinuous stream of individual data values in character 
form. Contrast with record data transmission. 


string. (1) A series of things, such as characters, in a 
line. (2) In PL/I, a contiguous sequence of characters or 
bits that is treated as a single data item. (3) A group of 
auxiliary storage devices connected to a system. The 
order and location in which each device is connected to 
the system determines the physical address of the device. 


structure. A collection of data items that need not have 
identical attributes. Contrast with array. 


structure variable. A variable that represents an aggre- 
gate of data items that might not have identical attri- 
butes. Contrast with array variable and scalar variable. 


subroutine. A procedure that has no RETURNS option 
in the PROCEDURE statement. Contrast with function. 


subroutine caf]. An entry reference that must represent a 
subroutine, followed by an optional and possibly empty 
argument list that appears in a CALL statement. Con- 
trast with function reference. 


undefined. Is used to indicate something that is not 
defined by the language and that may change without 
notice. Thus, programs that seem to work correctly 
when referencing undefined results do so by chance and 
are in error. 
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subscripted reference 5-3 
subscripts 5-2 
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array handling built-in functions 15-3 
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DIMENSION | 15-10 
HBOUND 15-11 
LBOUND 15-12 
result 15-3 
array mapping 5-11, 5-12 
arrays 5-1, 5-3, 12-38 
arrays of structures 5-5, 5-6 
declaration 5-5 
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by initialization of variables 5-24 
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scalar 13-1 
statement 4-2, 13-2 
examples 13-2 
string data 5-25 
structure 13-1 
symbol (=) 4-4, 9-10 
to control variable 13-7 


14-10 


to UNSPEC pseudovariable 15-25 
association of arguments and parameters 


14-1] 
ATAN built-in function 15-7 
ATAND built-in function 15-7 


14-9, 


ATANH built-in function 15-7 
attributes 12-1, 12-8 
additive 12-6 
ALIGNED _ 5-7, 12-40 
alternative 12-6 
defaults 12-6 
AUTOMATIC 5-18 
BASED 5-19, 12-42 
BINARY § 12-10 
BIT 12-16 
BUILTIN 12-36 
CHARACTER 12-16 
DECIMAL § 12-10 
description 12-1 
DIRECT 11-9 
ENVIRONMENT 7-1, 7-10 


EXTERNAL 4-16, 7-11, 12-40 


PILE 12-7 

FIXED 12-10 
FLOAT 12-10 
INITIAL 5-17 
INPUT 11-10, 11-23 


INTERNAL 4-16, 7-11, 12-40 


KEYED 12-7 

LABEL 12-31 

of returned value 14-4 
OPTIONS 12-36 
OUTPUT 11-10, 11-23 
parameter 14-3 
POINTER = 12-30 
precision 12-10 

PRINT 12-7 

RECORD 11-3 
required in declarations 4-13 
RETURNS = 12-35 
SEQUENTIAL 11-9 
STATIC 12-42 
STREAM § 11-3 
UNALIGNED _ 5-8, 12-40 
UPDATE 11-10, 11-23 
VARIABLE = 12-37, 12-38 
VARYING 12-18 
authority, file 6-3 
AUTO attribute 

See AUTOMATIC attribute 
automatic 5-18 

array specification 5-19 
storage allocation 5-18 


automatic (continued) 
storage and attribute 5-19 
storage class 5-16 
variable 5-18 
AUTOMATIC attribute 5-18 


B insertion character 12-23 


B or B1 bit constant identifier 12-16 


B-format item 11-32 


B-, B1-, and B4- format items 11-32, 11-34 


base 12-10 
attributes 
BINARY § 12-10 
DECIMAL 12-10 
default 12-10 
coded arithmetic data 12-10 
based 5-20, 5-23 
storage and attribute 5-19 


ADDR built-in function 12-31 
NULL built-in function 12-31 


storage class 5-16 
variable 
reference 5-20 
variable reference and pointer 
qualification 5-20, 5-21 


variables and input/output 5-24 


BASED attribute 5-19, 12-42 
basic program structure 4-1 
basic reference 9-1 

BEFORE value 7-17 


See also KEYSEARCH parameter of the 


OPTIONS option 
BEGIN statement 4-11 
pairing with END statement 
begin-block activation 4-11 
begin-block ending 4-12 


13-10 


begin-blocks 4-11, 4-6, 4-11—4-12 


as on-units 10-3 
BFR value 

See BEFORE value 
BIN attribute 

See BINARY attribute 


BINARY and DECIMAL attributes 


BINARY attribute 12-10 
BINARY built-in function 15-8 


12-10 


Index 


X-3 


binary fixed-point data 12-12—12-13 boundary 


binary fixed-point value 12-12 alignment 5-9 
binary floating-point data 12-14 byte 5-7 
binary floating-point value 12-14 doubleword 5-7 
binary synchronous communications files 6-10 halfword 5-7 
bit 9-9, 12-16 integral 5-7 
Bor Bl 12-16 quadword 5-7 
B4 12-16 word 5-7 
comparison 9-11 bounds of an array 12-38 
constant 12-16 breakpoints 3-5 
conversion example 3-5 
to arithmetic 5-31 browsing compiler listings 2-4 
. to character 5-33 BSC files 
data 12-16, 12-17 See binary synchronous communications files 
maximum length 12-17 BUFSIZE option of the ENVIRONMENT attri- 
operations 9-10 bute 7-5 
operators 9-9, 4-4 buffer length default 7-5 
target 5-33 built-in function reference 15-1 
value 12-16 built-in functions 15-1 
null 12-17 ABS 15-5 
BIT and CHARACTER attributes 12-16 ACOS 15-6 
BIT attribute 12-16 ADDR 15-6 
BIT built-in function 15-8 aggregate arguments 15-5 
bit data 12-16 arithmetic 15-2 
alignment 5-8, 12-40 array handling 15-3 
defaults 5-8, 12-40 ASIN 15-6 
bit format items ATAN 15-7 
B ATAND 15-7 
See B-format item ATANH 15-7 
Bl BINARY | 15-8 
See B1l-format item BIT 15-8 
B4 calling 15-1 
See B4-format item CHARACTER 15-8 
blanks 4-5 classification 15-2 
block activation 4-7 computational 15-2 
block ending 4-7, 4-9 condition handling 15-3 
BLOCK option of the ENVIRONMENT conversion 5-28 
attribute 7-7 conversion of arguments 15-2 
blocks 4-6—4-12 COPY 15-8 
activation 4-7 COS 15-9 
begin 4-6 COSD 15-9 
ending 4-7 COSH_ 15-9 
external 4-6 DATE 15-9 
internal 4-6 DECIMAL 15-9 
nested 4-12 declaration 15-1 
procedure 4-6 DIMENSION | 15-10 


DIVIDE 15-10 
empty argument lists 15-5 
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built-in functions (continued) built-in subroutines 15-4, 15-5 


EXP 15-11 PLICOMMIT 8-59, 15-4 
FIXED 15-11 PLIDUMP 3-14, 15-4 

FLOAT 15-11 PLIIOFDB 3-17, 15-5 
HBOUND 15-11 PLIOPNFDB _ 3-17, 15-5 
INDEX 15-12 PLIRCVMSG 15-5 
input/output 15-4 PLIRETC 15-4 

LBOUND 15-12 PLIROLLBACK 8-60, 15-5 
LENGTH § 15-12 BUILTIN attribute 12-36—12-37 
LINENO = 15-12 BY NAME assignment 13-3, 13-5 
LOG 15-12 by-name-parts-list 13-3 

LOGIO 15-13 rules for assignment 13-3 
LOG2_ 15-13 BY option 13-7 

mathematical 15-3 byte boundary 5-7 

MAX 15-13 Bl-format item 11-32 

MIN = 15-13 B4 bit constant identifier 12-16 
miscellaneous 15-4 B4-format item 11-32 

MOD 15-14 

NULL 15-14 Cc 

ee \ ae : calculating string length and precision 5-29 


CALL statement 14-7, 14-9 

calling a block 4-10 

calling a non-PL/I program 2-23 
calling a PL/I program from a non-PL/I 


ONKEY 15-15 
PLIRETV 15-19 
PLISHUTDN _ 15-20 
reference 15-1 


program 2-24 
ER ie calling a procedure 14-4, 14-11 
SIGN 15-21 calling levels 3-10 
SIN 15-22 ceil values 
SIND 15-22 table of . 9-9 
SINH 15-22 CHAR attribute 


See CHARACTER attribute 
character 12-18 
comparison 9-1] 
constant 
maximum length 12-18 


SQRT 15-22 
storage control 15-4 
string handling 15-2 
SUBSTR 15-23 


TAN 15-24 conversion 
TAND 15-24 to arithmetic 5-31 
TANH = 15-24 ‘ 

to bit 5-34 
TIME 15-24 data 12-18 
TRANSLATE = 15-24 target 5-3] 
TRUNC § 15-25 ee 
UNSPEC 15-25 null 12-18 


used in conversion 5-28 

VERIFY 15-26 
built-in functions and pseudovariables 15-1, 15-26 
built-in names 15-5 


of picture data 12-19 
variable declaration 12-18 
CHARACTER attribute 12-16 
CHARACTER built-in function 15-8 


Index X=-5 


character format item 
See A-format item 
characters B-14 
and EBCDIC codes _ B-15 
extralingual B-15 
language 
alphabetic B-14 
digits B-14 
special B-14 
CL commands 
ADDLFM 8-2 
ADDTRC_ 3-7 
BGNCMTCTL 7-7, 8-58, 8-62 
CALL 2-22 
CHGDBG 3-3 
CHGHLLPTR 3-12 
CRTLF 8-2 
CRTPLIPGM 2-5, 7-12 
CRTTAPF 7-6 
CRTxxxF 7-6 
DSPTRCDTA 3-7 
ENDCMTCTL 7-7, 8-58 
ENTDBG 3-3 
GRTOBJAUT 2-15 
MONMSG_ 2-22 
OVRDBF 6-2, 6-7, 7-6 
OVRTAPF 7-6 
RCLRSC 7-11 
RTVJOBA 2-22 
RVKOBJAUT 6-3 
SBMJOB_ 6-10 
WRKJOB 2-22 
classification of built-in functions 15-2, 15-4 
CLOSE statement 7-11, 11-8 
following run time error 7-13 
closing an unopen file 11-8 
coded arithmetic data 
base 12-10 
binary fixed-point 12-12 
binary floating-point 12-14 
conversion to bit 5-33 
conversion to character 5-31 
decimal fixed-point 12-11 
decimal floating-point 12-13 
precision 12-10 
scale 12-10 
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COL format item 
See COLUMN format item 
colon (:) 4-5 
COLUMN format item 11-34 
combination of operations 9-14, 9-16 
COMMA in “INCLUDE directive 8-75 
comma (,) 4-5 
comments 4-5 
commercial “at” sign (@) B-14 
commitment control 8-58 
performance considerations 8-61 
PLICOMMIT 8-59 
PLIROLLBACK 8-60 
program examples 8-64—8-73 
specified by ENVIRONMENT attribute 7-6 
using record locks 8-62 
COMMITTABLE option of the ENVIRON- 
MENT attribute 7-6, 8-59 
communication with non-PL/I programs 2-23 
communications files 6-10 
comparison 9-10 
operations 9-13 
problem data 9-11 
program control data 9-11 
tables 9-12 
operators 9-10 
compiler directives 
See also directives 
entering 2-4 
in source programs 2-5 
using 2-16 
*PROCESS 2-16 
%INCLUDE 2-16 
%PAGE 2-18 
%PROCESS 2-16, 2-18 
Y%SKIP 2-19 
compiler output 2-19 
compiler segments A-5 
compiler service A-1 
compiling source programs 2-5 
CRTPLIPGM command 2-5 
composite symbols B-15 
computational built-in functions 15-2 
concatenating copies of a string 
See COPY built-in function 
concatenation 9-14 
operations 9-14 
operator (||) 9-14 


condition codes D-1 
conversion condition D-7 
ENDFILE condition D-7 
ENDPAGE condition D-7 
fixedoverflow condition D-11 
KEY condition D-12 
overflow condition D-13 
record condition D-13 
UNDEFINEDFILE condition D-15 
underflow condition D-16 
zerodivide condition D-16 
condition handling 10-1, 15-3 
built-in functions 15-4 
ONCODE 15-14 
ONFILE = 15-15 
ONKEY 15-15 
scope of result 15-3 
scope of values 10-4 
conditional picture characters 12-23 
conditions D-1, 10-2, D-1—D-6, D-16 
action when raised 10-1 
conversion D-2 
ENDFILE D-2 
ENDPAGE D-7, D-2 
ERROR  D-7, D-3 
established action 10-2 
fixedoverflow D-3, D-10 
groups of 10-1 
in ON statement 10-2 
in SIGNAL statement 10-4 
investigating cause of 15-3 
KEY D-11, D-4 
list of D-6, D-16 
overflow D-4, D-12 
record D-4, D-13 
storage D-5, D-13 
stringsize D-5, D-13 
TRANSMIT  D-S, D-13 
UNDEFINEDFILE D-14, D-5 
underflow D-6, D-16 
unspecifiable 10-2 
zerodivide D-6, D-16 
conditions in ON and SIGNAL statements 
10-2 
ENDFILE D-2, 10-1 
ENDPAGE  D.-?7, D-2, 10-1 
ERROR  D-7, D-3, 10-1 
KEY D-11, D-4, 10-1 


10-1, 


conditions in ON and SIGNAL statements (con- 
tinued ) 
UNDEFINEDFILE D-14, D-S, 10-1 
CONSECUTIVE option of the ENVIRONMENT 
attribute 7-2 
constants 4-2 
bit 12-16 
character 12-18 
decimal fixed-point 12-11 
decimal floating-point 12-13 
entry 12-32 
file 11-3 
label 12-31 
named 12-9 
contained in 4-12 
contextual declaration 4-13 
built-in functions or built-in subroutines 4-13, 
15-1 
overriding 4-13 
scope 4-13 
contextual declaration of built-in functions or 
built-in subroutines 15-1 
control characters 7-4 
control format items 11-31, 11-29 
COLUMN format item 11-34 
LINE format item 11-39 
PAGE format item 11-39 
processing 11-29 
SKIP format item 11-39 
X-format item 11-40 
control language (CL) 1-1 
conversion 
to arithmetic 5-29 
to bit 5-33 
to character 5-31 
conversion built-in functions 
conversion condition D-2 
conversion of problem data 
See data conversion 
conversion rules 5-29, 5-34 
converted precision 15-3 
COPY built-in function 15-8 
copying a string 
See COPY built-in function 
COS built-in function 15-9 
COSD built-in function 15-9 


5-28, 5-29 
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COSH built-in function 15-9 data attributes (continued) 


CR picture character 12-26 BIT 12-16 
Create PL/I Program command BUILTIN = 12-36 
See CRTPLIPGM command CHARACTER § 12-16 
creating null pointer value 15-4 DECIMAL 12-10 
creating programs 2-1 dimension 12-38 
See also compiling source programs FILE 12-7 
credit and debit characters 12-26, 12-30 FIXED 12-10 
CR (credit) picture character pair 12-26 FLOAT 12-10 
DB (debit) picture character pair 12-26 label 12-31 
CRTPLIPGM command 2-5 POINTER = 12-30 
compiler output 2-5 precision 12-10 
examples 2-15 structure 5-3 
first CRTPLIPGM command screen 2-6 UNALIGNED _ 5-8, 12-40 
options and parameters 2-15 VARIABLE = 12-37, 12-38 
second CRTPLIPGM command screen 2-9 VARYING 12-18 
third CRTPLIPGM command screen 2-12 data attributes of target 5-27 
*DIAGNOSE option of the GENOPT param- data base files 6-4, 6-8, 8-1 
eter 2-16 access paths 6-4 
CTLASA option of the ENVIRONMENT attri- externally described 8-2 
bute 7-4 logical files 6-4 
currency symbol ($) B-14 members of 6-6 
physical files 6-4 
D program examples 8-2—8-22 
data program-described 8-2 
, record formats 6-5 
alignmen a use of 8-1 
Pca ee ae data conversion 5-27, 5-24, 5-27—5-35, 9-5 
ormat items 11-31, 11-29 
lists 11-23 accuracy of values 5-31 
‘ built-in functions 
mapping 5-9 


BINARY 15-8, 5-28 
BIT 15-8, 5-28 
CHARACTER 15-8, 5-28 
DECIMAL 15-9, 5-28 
FIXED 15-11, 5-28 
FLOAT 15-11, 5-28 

by assignment 5-29 


organization 5-1 
specifications 11-23 
transmission statements 11-2, 11-10, 11-23 
transmitted 11-10 
data aggregate 5-1, 12-38 
arguments 15-5 
arrays 5-1, 12-38 


assignment 13-1 examples 5-34 
structures 5-3 in arithmetic operations 

data alignment 5-7 exponentiation 9-5 
bit 5-8. 12-40 . non-exponentiation 9-5 
byte 5-7 in comparison operations 9-11 
halfword 5-7 in operational expressions 9-4 
quadword 5-7 on assignment 
word 5-7 precision 5-26 

string length 5-25 


data attributes 


: operands 5-28 
sear Ng i 12-40 problem data 5-27 
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data conversion and assignment 
data conversion in arithmetic operations 9-5 
data description specifications 


data format 1tems 


data lists 


data conversion (continued) 


program control data 5-27 

rules 5-29 

to arithmetic 
from arithmetic 5-29 
from bit 5-31 
from character 5-31 

to bit 
from arithmetic 5-33 
from character 5-34 
from fixed-point binary 5-33 
from fixed-point decimal 5-33 
from floating-point binary 5-34 
from floating-point decimal 5-34 
from picture 5-33 

to character 
from bit 5-33 
from coded arithmetic 5-31 
from fixed-point binary 5-31 
from fixed-point decimal 5-32 
from floating-point binary 5-32 
from floating-point decimal 5-32 
from picture 5-33 

5-24, 5-27 


examples 

DDS for subfiles 8-29 

display file DDS 8-23 

logical file DDS 8-4 

physical file DDS 8-3 

printer file DDS 8-50 

%INCLUDE examples 8-79 
mapping DDS data types to a PL/I 

program 8-77 

record format definition 6-5 
use of 8-2, 8-23, 8-29, 8-50 
used with externally described data files 6-11 
11-31, 11-29, 11-34, 11-37 
A-format item 11-31 
association with data item 
B-format item 11-32 
Bl-format item 11-32 
B4-format item 11-32 
E-format item 
11-27, 11-23, 11-27—11-28 
array data transmission 11-41 
assignment 11-41 


11-29 


data lists (continued) 
data list item 11-27 
iterative specification 11-28 
structure data transmission 
data management 
record formats 6-11 
externally described 6-11 
program-described 6-12 
system considerations 
device independence 6-1 
file independence 6-1 
security 6-3 
system override considerations 
types of files 6-4—6-10 
data base files 6-4, 8-1 
device files 6-8, 8-49 
data mapping 5-9, 5-15 
DDS to PL/I 8-77 
data organization 5-1, 5-6 
data set organization 11-9 
data sets 11-1, 11-2-—11-9 
recording datain 11-9 
data specifications 11-23 
data transmission 
input 11-1 
output 11-1 
record 11-1 
statements 
Stream 11-1 
data transmission statements 
DELETE 11-16 
GET 11-24 
PUT 11-25 
READ 11-11 
record 11-1 
REWRITE 
stream 11-23 
WRITE 11-14 
data transmitted 11-10 
DATE built-in function 15-9 
DB picture character 12-26 
DCL statement 
See DECLARE statement 
DDM files 6-10 
DDS 
See data description specifications 


11-41 


11-2, 11-10, 11-23 


11-15 


6-2 


Index 


11-1, 11-10, 11-23 
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DDS to PL/I mapping 8-77 
debug 
active blocks in a program 3-13 
calling levels 3-10 
changing varying length strings 3-12 
displaying level numbers 3-13 
floating-point variables 3-12 
fully qualified names 3-11 
PLIDUMP 3-14 
PL/I pointers 3-12 
PL/I storage 3-10 
references to static variables 3-13 
scoping of names 3-11 
specifying variables by ODV number 3-13 
using 3-10 
debugging aids 3-1 
CPF test and debug features 
breakpoints 3-5 
test libraries 3-3 
traces 3-7 
PL/I debugging features 
ON conditions 3-17 
PLIDUMP 3-14, 15-16 
PLIIOFDB 3-17, 15-16 
PLIOPNFDB 3-17, 15-17 
DEC attribute 
See DECIMAL attribute 
DECIMAL attribute 12-10 
DECIMAL built-in function 15-9 
decimal fixed-point constant 12-11 
precision 12-11 
decimal fixed-point data 12-11, 12-12 
decimal fixed-point value 12-11 
decimal floating-point constant 12-13 
precision 12-13 
decimal floating-point data 12-13 
decimal floating-point value 12-13 
declaration 
CAUTION for multiple declarations 4-14 
contextual 4-13 
explicit 4-13 
DECLARE statement 7-1, 12-1 
declaring 12-31 
arrays 12-38 
arrays of structures 5-5 
BASED variables 5-19, 12-42 
binary fixed-point variables 12-12 
binary floating-point variables 12-14 
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declaring (continued ) 
bit variables 12-17 
built-in functions or built-in subroutines 
character variables 12-18 
decimal fixed-point variables 12-12 
decimal floating-point variables 12-13 
entry constant 12-32 
entry variables 12-32 
file constants 12-7 
label constants 12-31 
label variables 12-31 
parameters 14-2 
pointer variables 12-30 
structures 5-4, 12-38—12-39 
declaring a built-in function or built-in 
subroutine 15-1 
defaults 12-4] 
A-format item output field-width 11-31 
alternative attributes 12-6 
bit variable length 12-16 
buffer length 7-5 
B, B1, and B4 format items output 
field-width 11-33 
character variable length 12-16 
do-group expression_3 13-7 
E-format item fractional-digits 11-35 
F-format item 11-37 
for SKIP option 11-26 
line size 11-5 
lower bound 12-39 
page size 11-6 
precision 12-1] 
scope 14-3 
SKIP format item relative-line 11-40 
“SKIP statement number-of-lines 2-19 
defining a procedure 14-1, 14-4 
DELETE statement 11-16 
OPTIONS option 7-13 
with RECORD parameter 7-17 
delimiters 4-3, 4-5 
assignment symbol(=) 4-5 
blank 4-5 
colon (:) 4-5 
comma (;) 4-5 
comment 4-5 
operators 4-4 
parentheses () 4-5 
percent statements 4-5 


15-1 


delimiters (continued) 
period (.) 4-5 
pointer (->) 4-5 
semicolon (;) 4-5 
DESCRIBED option of the ENVIRONMENT 
attribute 7-6 
descriptions of built-in functions and 
pseudovariables 15-5, 15-26 
device files 6-8, 6-10, 8-49 
BSC files 6-10 
communications files 6-10 
DDM files 6-10 
display files 6-8, 8-22 
externally described 8-50 
inline files 6-10 
program example 8-50 
program-described 8-50 
use of 8-49 
device independence 6-1 
spooling 6-2 
digit and decimal point characters 12-22, 12-23 
alignment of value 12-23 
digits B-14 
DIM built-in function 
See DIMENSION built-in function 
dimension attribute 12-2, 12-38 
DIMENSION built-in function 15-10 
DIRECT attribute 11-9, 12-7 
directives 2-16, 2-22, 4-1—4-2 
definition 4-1 
%INCLUDE 8-73, 8-82 
%PAGE 2-18 
%PROCESS 2-18 
%SKIP 2-19 
diskette device files 
obligatory use of BUFSIZE option 7-5 
display files 6-8, 6-9, 8-22 
externally described 8-23 
program examples 8-23—8-49 
subfiles 6-9 
use of 8-22 
displaying and printing messages 3-3 
DIVIDE built-in function 15-10 
DO statement 13-5, 13-10 
examples 13-8—13-10 
pairing with END statement 13-5, 13-10 


do-group 13-5 
effect of processing 13-7 
ending 13-5, 13-11 
iterative 13-5 
maximum nesting 13-8 
noniterative 13-5 
simple 13-6 
TO and BY versus REPEAT 13-7 
transferring into 13-8 
doubleword boundary 5-7 
drifting characters 12-24 
dummy argument 14-10 
DUMMYDCL null character string generated by 
YINCLUDE directive 8-75 
dynamic storage allocation 5-16 


E 
E-format item 11-34, 11-37 
EBCDIC codes_ B-15, E-1 
edit-directed data transmission 
See stream data transmission 
editing source programs 
description 2-1 
entering SQL statements 2-5 
PL/I syntax checker 2-2 
using SEU 2-2 
editing the source program 2-1 
effect of recursion on automatic variables 14-12 
elementary expression 9-1 
elements of a PL/I statement 4-2, 4-5 
delimiters 4-3 
identifiers 4-3 
ELSE unit 13-13 
empty argument lists 15-5 
END statement 13-10, 13-11 
block ending 13-11 
do-group ending 13-11 
inafunction 13-11 
pairing with BEGIN, DO, and PROCEDURE 
statements 13-11 
program ending 13-11 
ENDFILE condition D-2, D-7 
ending 
aprogram 4-6 
begin-blocks 4-12 
blocks 4-7 
procedures 4-11 
program processing 2-22 
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ENDPAGE condition D-2, D-3, D-7 
entering source programs 2-1 
entering SQL statements 2-5 
entry 12-32 
argument 14-7 
built-in name 14-7 
constant 14-2 
data 12-36 
reference 12-32, 14-7 
variable 12-32 
entry data 12-32 
ENV attribute 
See ENVIRONMENT attribute 
ENVIRONMENT attribute 7-1, 7-10, 12-8 
BLOCK option 7-7 
BUFSIZE option 7-5 
COMMITTABLE option 7-6, 8-59 
CTLASA option 7-4 
DESCRIBED option 7-6 
file locking options 
EXCL 7-3 
EXCLRD 7-3 
file organization options 
CONSECUTIVE 7-2 
INDEXED 7-2 
INTERACTIVE 7-3 
key options 
KEYDISP 7-4 
KEYLENGTH 7-4 
NOINDARA option 7-8 
EQL value 
See EQUAL value 
EQUAL value 7-17 
See also KEYSEARCH parameter of the 
OPTIONS option 
ERROR condition D-3, D-7—D-10 
finding the cause 10-1 
raised by DELETE or REWRITE 8-64 
raised by I/O statement options 6-3 
errordump 3-16 
error finding in programs 3-1 
established action 10-2, 10-4 
implicit 10-2 
ON statement 10-2 
scope of 10-4 
EXCL option of the ENVIRONMENT 
attribute 7-3 
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EXCLRD option of the ENVIRONMENT attri- 
bute 7-3 
EXP built-in function 15-11 
explicit declaration 4-13 
of a parameter 4-13 
scope of 4-13 
explicit declaration of built-in functions or built-in 
subroutines 15-1 
exponentiation 9-5 
expression 9-1 
operational 9-4 
scalar 9-] 
expressions as subscripts 5-3 
EXT attribute 
See EXTERNAL attribute 
extent 12-39 
extents for automatic variables 5-19 
EXTERNAL attribute 4-16, 7-11, 12-40 
defaults 12-41 
scope of name 4-16 
external name 11-4, 12-41 
maximum length 12-41 
external procedure 4-9, 4-6 
external text 
inclusion of 2-16 
externally described files 
data base files 8-2 
device files 8-50 
display files 8-23 
use of % INCLUDE directive 8-75 
externally described record formats 6-11 
defining with DDS 6-11 
level checking 6-12 
use of % INCLUDE directive 8-75 
extralingual characters B-15 


F 
F-format item 11-37, 11-39 
factoring 
attributes 12-2 
nesting 12-2 
structure level numbers 12-2 
factoring of attributes 4-13, 12-2 
field name 5-3 
file 11-4 
additive attributes 12-6 
alternative attributes 12-6 
characteristics, specified by ENVIRONMENT 
attribute 7-4 


file (continued) 
closing 11-8, 7-11 
constant 11-3 
declaration 
ENVIRONMENT attribute 7-1 
EXTERNAL attribute 7-11 
INTERNAL attribute 7-11 
default construction for OPEN statement 11-5 
description with DDS 8-2, 8-23, 8-29, 8-50 
determining current state of 15-4 
independence 6-1 
locking 6-6, 7-3 
management 8-1—8-58 
opening 7-11 
examples 11-7 
implicit 11-6 
implied attributes 11-6 
sources of information 11-6 
organization, specified by ENVIRONMENT 
attribute 7-2 
redirection 6-3 
scope 7-11, 12-7 
security 6-3 
authority 6-3 
ownership 6-3 
sharing 7-11 
spooling 6-2 
types 6-4 
See also file types supported by AS/400 PL/I 
FILE attribute 12-7 
file locking options of the ENVIRONMENT attri- 
bute 7-3 
EXCL 7-3 
EXCLRD 7-3 
FILE option 
for record data transmission 11-18 
for stream data transmission 11-26 
in CLOSE statement 11-8 
in GET statement 11-26 
in OPEN statement 11-26 
in PUT statement 11-26 
file types supported by AS/400 PL/I 6-4 
data base files 6-4, 8-1 
logical files 6-4 
members 6-6 
physical files 6-4 
device files 6-8, 8-49 
BSC files 6-10 
communications files 6-10 


file types supported by AS/400 PL/I (continued) 
device files (continued) 
DDM files 6-10 
inline files 6-10 
subfiles 6-8, 8-22 
FIXED and FLOAT attributes 12-10 
FIXED attribute 12-10 
FIXED buult-in function 15-11 
fixed overflow condition D-3, D-4, D-10—D-11 
fixed-point binary to bit conversion 5-33 
fixed-point binary to character conversion 5-31 
fixed-point decimal to bit conversion 5-33 
fixed-point decimal to character conversion 5-32 
fixed-point format item 
See F-format item 
FLOAT attribute 12-10 
FLOAT built-in function 15-11 
floating-point binary to bit conversion 5-34 
floating-point binary to character conversion 5-32 
floating-point decimal to bit conversion 5-34 
floating-point decimal to character 
conversion 5-32 
floating-point format item 
See E-format item 
floating-point variables in test environment 3-12 
FOFL condition 
See fixed overflow condition 
format items 
control 
COLUMN 11-34 
LINE 11-39 
PAGE 11-39 
SKIP 11-39 
X 11-40 
data 
A 11-31 
B 11-32 
Bl 11-32 
B4 11-32 
E 11-34 
F 11-37 
format lists 11-23 
format items 11-29 
iteration factor 11-28 
FREE statement 5-23 
FROM option 11-19 
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fully qualified names 3-11 
function reference 14-4, 14-6 
functions 14-1 
arithmetic built-in 15-2 
array handling built-in 15-3 
attributes of returned value 14-4 
built-in 15-1 
calling 14-1 
condition handling built-in 15-3 
conversion of value 14-3 
data processed 14-1 
definition 14-1 
input/output built-in 15-4 
mathematical built-in 15-3 
miscellaneous built-in 15-4 
return from 14-1 
RETURN statement in 14-4 
storage control built-in 15-4 


G 
general statements 13-1, 13-20 
GET statement 11-24 
GO TO statement 13-11, 13-13 
GOTO statement 

See GO TO statement 
group 

See do-group 


H 

halfword boundary 5-7 
HBOUND built-in function 15-11 
how to read syntax diagrams vi 


I 

IBM extensions to AS/400 PL/I B-1, B-13 

identifiers 4-3 
maximum length 4-3 

identifying location of variable 15-4 

IF statement 13-13, 13-14 
comparison operation 9-10 
examples 13-14 

implicit action for condition 10-2, D-1 
conversion condition D-2 
ENDFILE condition D-2 
ENDPAGE condition D-3 
ERROR condition D-3 
fixedoverflow condition D-4 
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implicit action for condition (continued) 
KEY condition D-4 
overflow condition D-4, D-12 
record condition D-4 
storage condition D-5, D-13 
stringsize condition D-5 
TRANSMIT condition D-5 
UNDEFINEDFILE condition D-5, D-16 
underflow condition D-6, D-16 
zerodivide condition D-6, D-16 
implicit opening 11-6, 11-7 
implied attributes 11-6 
including text in source program 
See % INCLUDE directive 
independence 
device 6-1 
file 6-1 
INDEX built-in function 15-12 
INDEXED option of the ENVIRONMENT attri- 
bute 7-2 
indicators 
examples 8-43—8-49 
use with % INCLUDE directive 8-76 
INDICATORS element type in % INCLUDE 
directive 8-74 
INDICATORS parameter of the OPTIONS 
option 7-19 
with READ 7-19 
with REWRITE 7-19 
with WRITE 7-19 
industry standards viii 
infix operation 9-4 
infix operator 9-1 
inherited dimensions 
See arrays of structures 
initial 
See initial procedure 
INIT attribute 
See INITIAL attribute 
INITIAL attribute 5-17, 5-18, 12-42 
and static external variables 5-17 
INITIAL attribute and inherited dimensions 5-17 
initial procedure 4-6, 14-7 
initial value 5-17, 12-43 
initialization 5-17, 12-43 
array variable 5-17, 12-43 
scalar variable 5-17, 12-43 


inline data files 6-10 
inline files 6-10, 7-12 
input 11-1 
input and output 11-1, 11-8 
statements 11-1 
input and output statements 
See data transmission statements 
INPUT attribute 11-10, 11-23, 12-7 
INPUT element type in % INCLUDE 
directive 8-74 
INPUT option in OPEN statement 11-4 
input/output built-in functions 15-4 
LINENO = 15-12 
SAMEKEY 15-21 
INPUT, OUTPUT, and UPDATE 
attributes 11-10, 11-23, 12-7 
default 12-7 
insertion characters 12-23, 12-24 
and drifting string 12-25 
B 12-23 
. 12-23 
/ 12-23 
, 12-23 
INT attribute 
See INTERNAL attribute 
integral boundary 5-7 
INTERACTIVE option of the ENVIRONMENT 
attribute 7-3 
interlanguage calls 2-23 
calling a PL/I program from a non-PL/I 
program 2-24 
matching PL/I attributes in 
BASIC 2-27 
CL 2-27 
COBOL 2-27 
RPG 2-24 
non-PL/I program 2-23 
INTERNAL and EXTERNAL attributes 4-16, 
12-40 
internal and external procedures 4-9, 4-10 
INTERNAL attribute 4-16, 7-11, 12-40 
defaults 12-41 
scope of name 4-16 
internal procedure 4-9, 4-6 
internal to 4-12 
interrupting program processing 2-22 


INTO option 11-12, 11-18—11-19 
ITERATE statement 13-14, 13-15 
examples 13-15 
iteration-factor 
in format list 11-28 
in INITIAL attribute 12-43 
iterative do-group 13-5 


K 
KEY condition D-4, D-11—D-12 
raised by duplicate key 8-62 
KEY element type in % INCLUDE directive 8-74 
KEY option 11-12, 11-20 
key options of the ENVIRONMENT 
attribute 7-3 
KEYDISP 7-4 
KEYLENGTH 7-4 
KEYDISP option of the ENVIRONMENT attri- 
bute 7-4 
KEYED attribute 12-7 
keyed sequence access path of AS/400 data base 
files 6-5 
obligatory coding of INDEXED option 7-2 
program examples 8-5, 8-10 
KEYFROM option 11-12, 11-21 
RESTRICTIONS 7-3, 7-6 
KEYLENGTH option of the ENVIRONMENT 
attribute 7-4 
KEYSEARCH parameter of the OPTIONS 


option 7-17 
values 
AFTER 7-17 
BEFORE 7-17 
EQLAFT 7-17 
EQLBFR_ 7-17 
EQUAL 7-17 


with READ 7-17 
KEYTO option 11-12, 11-21—11-22 
keyword 4-3 
keyword statement 4-2 
keywords 
See under individual keywords 
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L 
label 4-1, 12-31 
constant 
declaration 12-31 
prefix 4-2 
definition 4-1 
for DECLARE statement 12-1 
reference in GO TO statements 13-12 
statement 
See label prefix 
variable 12-31 
declaration 12-31 
LABEL attribute 12-31 
label data and attribute 12-31, 12-32 
language characters 4-1, B-15 
alphabetic characters B-14 
composite symbols B-14 
digits B-14 
special characters B-14 
LBOUND built-in function 15-12 
LEAVE statement 13-15, 13-16—13-17 
examples 13-17 
LENGTH built-in function 15-12 
level checking 
of externally defined files 6-12 
preventing with CL commands 7-6 
specified by ENVIRONMENT attribute 7-6 
level number, structure 5-4 
factoring 12-2 
range 12-1 
level, structure 12-1 
LINE format ttem 11-39 
line length specification 
See LINESIZE option 
LINE option 11-27 
LINENO built-in function 15-12 
lines on page, specifying number of 
See PAGESIZE option in OPEN statement 
LINESIZE option 11-5 
listing control directives 2-16 
%PAGE 2-18 
%SKIP 2-19 
locate mode 11-11 
locking 
files 6-6, 7-3 
records 6-7 
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LOG built-in function 15-12 


logical files 6-4 
DDS example 8-4 
logical level, structure 5-4 


LOG1O0 built-in function 15-13 
LOG2 built-in function 15-13 
lower-bound of array 12-38 


M 
MAIN option 14-3 
major structure name 5-3 
mapping 5-12 
array data 5-11 
DDS to PL/I 8-77 
scalar data 5-10 
structure data 
example 5-13 
rules 5-12 


mathematical built-in functions 


ACOS 15-6 

ASIN 15-6 

ATAN 15-7 

ATAND 15-7 
ATANH 15-7 
conversion of arguments 
COS 15-9 

COSD 15-9 

COSH 15-9 

EXP 15-11 

LOG 15-12 

LOGI1O 15-13 

LOG2 15-13 

scale of arguments 15-3 
scale of result 15-3 


SIN 15-22 
SIND 15-22 
SINH 15-22 
SQRT 15-22 
TAN 15-24 
TAND 15-24 
TANH = 15-24 


MAX built-in function 15-13 


maximum 
See also range 
array dimensions 12-39 
array length 12-39 


array upper-bound 12-39 
bit constant length 12-17 


15-3 


C 


maximum (continued) 
bit variable length 12-16 
block nesting 4-10 
blocks in external procedure 4-6 
character constant length 12-18 
character variable length 12-16 
digits in exponent 11-37, 12-13 
do-group nesting 13-8 
external entry name length 14-2 
external name length 12-41 
fractional digits in E-format item 11-34 
fractional digits in F-format item 11-37 
IF statement nesting 13-14 
iterative specifications in data list 11-28 
label prefix 4-1 
level number in DECLARE statement 12-1 
line number in LINE format item 11-39 
line size 11-5 
maximum depth 13-14 
member names in % INCLUDE 
statement 2-17 
name length 4-3 
on-units concurrently active 10-3 
on-units in external procedure 10-3 
page size 11-6 
parameters in procedure 14-2 
picture specification 
digit positions 12-20 
length 12-20 
precision 12-11 
binary fixed-point 12-11 
binary floating-point 12-14 
decimal fixed-point 12-11 
decimal floating-point 12-11 
relative-line number in SKIP format item or 
option 11-40 
statement label prefix 4-1 
structure length 5-5, 12-39 
structure level number in DECLARE 
statement 5-5, 12-39 
structure nesting 5-5, 12-39 
“INCLUDE statement nesting 2-17 
“SKIP statement number-of-lines 2-19 
members of data base files 6-6 
messages 
displaying 3-3 
printing 3-3 
using 3-1 


MIN built-in function 15-13 
minimum 
See also range 
bit variable length 12-16 
character variable length 12-16 
line size 11-5 
page size 11-6 
relative-line number in SKIP format item or 
option 11-40 
“SKIP statement number-of-lines 2-19 
minor structure name 5-3 
miscellaneous built-in functions 15-4 
DATE 15-9 
PLIRETV 15-19 
TIME 15-24 
MOD built-in function 15-14 
MODIFIED parameter of the OPTIONS 
option 7-20 
with READ 7-20 
move mode 11-11 
multiple declarations 4-14 
multiple pointer qualification 5-21, 5-22 


N 
name 4-3, 4-12, 9-1, 12-1 
factoring 12-2 
inan END statement 13-11 
scope 4-12 
name-list 12-1 
named constant 12-9 
NBRKEYFLDS parameter of the OPTIONS 
option 7-18 
with READ 7-18 
nested blocks 4-12 
new line, starting with OPEN statement 
See LINESIZE option 
NEXT value 7-18 
See also POSITION parameter of the 
OPTIONS option 
NOINDARA option of the ENVIRONMENT 
attnbute 7-8 
non-PL/I routines 12-36 
noniterative do-group 13-5 
nonstructure parameter descriptor 12-33 
normal return from condition D-1 
conversion condition D-2 
ENDFILE condition D-2 
ENDPAGE condition D-3 
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normal return from condition (continued) 
ERROR condition D-3, D-7 
fixedoverflow condition D-4 
KEY condition D-4 
overflow condition D-4, D-12 
record condition D-4 
TRANSMIT condition D-5 
UNDEFINEDFILE condition D-6 
zerodivide condition D-6, D-16 

null bit constant 12-17 

NULL built-in function 15-14, 12-31 
NULL 15-14 

null character constant 12-18 

null statement 4-2, 13-17—13-18 
examples 13-18 

number of digits 
picture specification 12-21 
precision attribute 12-11 

number sign (#) B-14 

numeric value of picture data 12-19 

NXT value 
See POSITION parameter of the OPTIONS 

option 


O 
ODV numbers 3-13 
OFL condition 
See overflow condition 
ON conditions 3-17 
See also conditions 
examples 3-18 
ON statement 10-2 
conditions in 10-1 
example 10-5 
precedence over implicit action 10-2 
scope 10-2 
second for same condition 10-4 
on-unit 
ending 10-3 
null 10-3 
running 10-3 
scope of names 10-3 
unlabeled begin-block 10-3 
unlabeled simple statement 10-3 
ONCODE built-in function 15-14 
ONCODE values 
See condition codes 


X-18 PL/I User’s Guide and Reference 


ONFILE built-in function 15-15 
ONKEY built-in function 15-15 
OPEN statement 7-11, 11-4—11-8 
processing 11-4 
opening a SYSPRINT file 7-12 
opening and closing files 11-4, 11-8 
CLOSE statement 11-8 
implicit opening 11-6 
OPEN statement 11-4 
opening stream files 7-12 
operating system 1-1 
operational expressions 9-4, 9-16 
operations 9-4, 9-10 
arithmetic 9-5 
bit 9-9 
combination of 9-14 
comparison 
problem data 9-11 
program control data 9-11 
concatenation 9-14 
conversion of 5-28 
infix 9-4 
prefix 9-4 
priority of 9-15 
operators 4-4, 9-5 
arithmetic 4-4 
bit 4-4, 9-9 
comparison 4-4, 9-10 
concatenation 9-14 
infix 9-5, 9-9 
prefix 9-5, 9-9 
priority of 9-15 
string 4-4 
options 
ASSEMBLER = 12-36 
BY 13-7 
FILE in CLOSE statement 11-8 
FILE in DELETE, READ, REWRITE, or 
WRITE statement 11-18 
FILE in GET or PUT statement 11-26 
FILE in OPEN statement 11-4 
FROM 11-19 
INPUT 11-4 
INTO 11-18 
KEY 11-20 
KEYFROM 11-21 
KEYTO 11-21 
LINE 11-27 


C 


options (continued) 
LINESIZE 11-5 
MAIN 14-3 
OPTIONS 7-13, 14-3 
OUTPUT 11-4 
PAGE 11-26 
PAGESIZE 11-6 
RECURSIVE 14-3 
REENTRANT 14-3 
REPEAT 13-7 
RETURNS 14-3 
SET 11-19 
SKIP 11-26 
TITLE 11-4 
TO 13-7 
UNTIL 13-6 
UPDATE 11-4 
WHILE 13-6 
OPTIONS attribute 12-36 
options of record data transmission 
statements 11-14, 11-15, 11-16—11-22 
FILE 11-18 
FROM 11-19 
INTO 11-18 
KEY 11-20 
KEYFROM 11-21 
KEYTO 11-21 
OPTIONS option 7-13 
with INDICATORS parameter 7-19 
with RECORD parameter 7-16 
SET 11-19 
OPTIONS option 7-13, 11-12, 14-3 
INDICATORS parameter 7-19 
KEYSEARCH parameter 7-17 
MODIFIED parameter 7-20 
NBRKEYFLDS parameter 7-18 
POSITION parameter 6-6, 7-17 
RECORD parameter 7-15 
organization of a data set 11-9 
OTHER (OTHERWISE) statement 13-18 
OTHERWISE statement (abbr: OTHER) 13-18 
output 11-1 
OUTPUT attribute 11-10, 11-23, 12-7 
OUTPUT element type in % INCLUDE 
directive 8-74 
OUTPUT option in OPEN statement 11-4 


overflow condition D-4, D-12—D-13 
override of member definition for a file 6-2 
override of PL/I file declarations 6-2 
ownership, file 6-3 


P 
page eject on source program listing 
See %PAGE statement 
PAGE format item 11-39 
PAGE option 11-26 
PAGESIZE option in OPEN statement 11-6 
pairing 
BEGIN and END statement 13-10 
DO and END statement 13-10 
PROCEDURE and END statement 13-10 
parameter 14-2, 12-33, 14-3 
and argument, association of 14-9 
attribute specification 14-3 
attributes 14-3 
declaration 14-2 
default scope 14-3 
descriptor 
list 12-33 
nonstructure 12-33 
structure 12-33 
lengths and bounds 14-4 
maximum in a procedure 14-2 
parameter descriptor list 12-33 
parameters 14-1 
parentheses () 4-5 
percent statements 4-5 
performance considerations 
commitment control 8-61 
period (.) 4-5 
physical files 6-4 
DDS example 8-3 
PIC attribute 
See picture 
picture 
character 
- 12-25 
after value truncation to zero 12-25 
and zero suppression 12-23 
B 12-23 
conditional 12-23 
CR 12-26 
credit and debit 12-26 
DB 12-26 
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picture (continued) 
character (continued) 
decimal point 12-22 
digit 12-22 
drifting 12-24 
drifting currency 12-24 
drifting sign 12-24 
insertion 12-23 
S 12-25 
sign and currency characters 12-24 
static 12-24 
Vs 12-22, 12-23 
Z 12-23 
zero suppression 12-23 
9 12-22 
. 12-23 
+ 12-25 
$ 12-25 
* 12-23 
/ 12-23 
, 12-23 
conversion 
to bit 5-33 
to character 5-33 
to decimal fixed-point 12-21 
specification 12-19, 12-21 
picture data 12-19—12-22 
assignment 12-22 
base 12-21 
character value 12-19 
conversion to decimal fixed-point 12-21 
numeric value 12-19 
precision 12-21 
scale 12-21 
picture specification 12-19, 12-21, 12-30 
derived precision 12-21 
maximum length 12-20 
range of numeric values 12-21 
representation as a character value 12-21 
PLICOMMIT built-in subroutine 15-4 
use of 8-59 
with record locking 6-8 
PLIDUMP built-in subroutine 3-14, 15-4 
example 3-15 
PLIIOFDB built-in subroutine 3-17, 15-5 
PLIOPNFDB built-in subroutine 3-17, 15-5 
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PLIRCVMSG built-in subroutine 15-5 
PLIRETC built-in subroutine 15-4 
PLIRETYV built-in function 15-19 


PLIROLLBACK built-in subroutine 15-5 


use of 8-60 
with record locking 6-8 
PLISHUTDN built-in function 15-20 
PLISHUTDN = 15-20 
PL/I keywords 4-3 
See also under individual keywords 
PL/I source program 
description 2-1 
entering SQL statements 2-5 
PL/I syntax checker 2-2 
using SEU 2-2 
PL/I syntax checker 2-2 
point of calling a block 4-10 
POINTER attribute 12-30 
pointer built-in functions 12-31 
ADDR 12-31 
NULL 12-31 
pointer data and attribute 12-30 
pointer (->) 4-5, 12-30 
expression 5-20 
qualification 5-20 
qualified reference 5-20 
qualifier 5-20, 9-1 
value 
creation 12-30 
variable 12-42 
pointers 3-12 
POSITION parameter of the OPTIONS 
option 7-17 
values 
FIRST 7-18 
LAST 7-18 
NEXT 7-18 
NXTEQL 7-18 
NXTUNQ 7-18 
PREVIOUS 7-18 
PRVEQL 7-18 
PRVUNQ 7-18 
with READ 6-6, 7-17 
precision 12-10 
attribute 12-10 
calculation 5-29 
coded arithmetic 12-10 
conversion 5-30 


J 


precision (continued) 
default 12-11 
precision attribute 12-10, 12-11 
prefix operation 9-4 
prefix operator 9-1 
PREVIOUS value 7-18 
See also POSITION parameter of the 
OPTIONS option 
PRINT attribute 12-7, 11-44, 12-7 
printer file examples 
printer file DDS 8-50 
using a printer file 8-50 
printing messages 3-3 
priority of operators 9-15, 9-16 
changed by parentheses 9-16 
problem data 9-4, 9-11, 12-9 
arithmetic 9-11 
bit 12-16 
character 12-18 
conversion 5-27 
operations 
arithmetic 9-5 
bit 9-9 
comparison 9-1] 
concatenation 9-14 
problem data conversion 
See data conversion 
PROC statement 
See PROCEDURE statement 
procedure 4-9, 4-10 
activation 4-11 
ending 4-11 
external 4-6 
internal 4-6 
PROCEDURE statement 14-2 
pairing with END statement 13-10 
procedures 4-9—4-1] 
function 14-1 
initial 
See initial procedure 
subroutine 14-2 


Process multiple compilation (see % PROCESS 


directive) 2-16 
processing an on-unit 10-3, 10-4 
processing mode 
locate 11-11 
move 11-11 


processing multiple compilations 
See % PROCESS directive 
program 4-6 
activation 4-6 
debugging 3-1 
elements 4-1 
ending 4-6, 13-11 
organization 4-12 
structure 4-1 
program control data 9-11, 12-2 
comparison operations 9-10 
conversion 5-27 
label 12-31 
pointer 12-30 
program elements 4-1 
program ending 13-11 
program ending, abnormal 2-22 
program examples 
CL program for breakpoints 3-5 
CL program for trace 3-7 
customer inquiry program 8-23 
reading from an arrival sequence file by 
RRN_ 8-20 
updating a file with a keyed access path 8-10 
updating a file with arrival sequence access 
path 8-7 
updating an arrival sequence file by RRN 8-17 
using a printer file 8-50 
using commitment control 8-65 
using externally defined indicators 8-43 
using PLICOMMIT and 
PLIROLLBACK 8-68 
using PLIDUMP 3-15 
using program-defined indicators 8-47 
using stream I/O 8-56 
using subfiles 8-29 
using % INCLUDE 8-79 
writing to a file with keyed sequence access 
path 8-5 
writing to an arrival sequence file by 
RRN_ 8-14 
program object 
abnormal ending 2-22 
ending 2-22 
interrupting 2-22 
running 2-22 
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program-described data base files 8-2 
program-described device files 8-50 
program-described record formats 6-12 
use of % INCLUDE directive 8-76 
programs 4-6 
PRV value 
See PREVIOUS value 
pseudovariables 15-5 
SUBSTR 15-23 
UNSPEC 15-25 
PTR attribute 
See POINTER attribute 
PUT statement 11-25 
PUT statement control options 11-26 
FILE 11-26 
LINE 11-27 
PAGE 11-26 
SKIP 11-26 


qualified reference 5-5 
quantitative restrictions 

See default, maximum, and minimum 
quotation mark 

See apostrophe (') 


R 


range 
binary floating-point values 12-14 
bit values 12-16 
character values 12-16 
decimal floating-point values 12-13 
picture specification numeric values 
READ option 11-12 
READ statement 11-11, 11-12 
OPTIONS option 


with INDICATORS parameter 7-19 
with KEYSEARCH parameter 7-17 


with MODIFIED parameter 7-20 


with NBRKEYFLDS parameter 7-18 
with POSITION parameter 6-6, 7-17 


with RECORD parameter 7-15 
READ 7-13, 11-11 
recognition of names 4-12 


RECORD and STREAM attributes 11-3, 12-7 


default 12-7 
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RECORD attribute 11-3, 12-7 
record condition D-4, D-13 
record data transmission 11-1, 11-3, 11-8—11-22 
OPTIONS option 7-13 
record blocking 11-9 
statements 
DELETE 7-13, 11-16 
processing 11-10 
REWRITE 7-13, 11-15 
WRITE 7-13, 11-14 
RECORD element type in % INCLUDE 
directive 8-74 
record formats 6-5, 6-11 
externally described 6-11 
defining with DDS 6-11 
level checking 6-12 
program-described 6-12 
record locking 6-7, 8-62 
RECORD parameter of the OPTIONS 
option 7-15 
with DELETE 7-17 
with READ 7-15 
with REWRITE 7-16 
with WRITE 7-16 
RECURSIVE option 14-3, 14-11 
recursive procedures 14-11 
redeclaring a built-in name 12-36 
redirection of files 6-3 
REENTRANT option 14-3 
reference 9-1 
array 9-1 
in DO statements 13-6 
qualified 5-5 
scalar 9-1 
structure 9-1 
subscripted qualified 5-6 
references and expressions 9-1, 9-16 
relationship of pointers and based variables 5-22 
relative record number 
program examples 8-14—8-22 
reopening a closed file 11-8 
REPEAT option 13-7 
repeating a string 
See COPY built-in function 
resource independence 11-2 
results of arithmetic operations 9-5, 9-9 


return code D-1 
RETURN statement 14-4 
for functions 14-4 
for subroutines 14-4 
RETURNS attribute 12-35—12-36 
RETURNS option 14-3 
conversion of value 14-3 
REWRITE statement 11-15, 11-16 
OPTIONS option 7-13 
with INDICATORS parameter 7-19 
with RECORD parameter 7-16 
ROUND built-in function 15-20 
RRN 
See relative record number 
running programs 
CL command CALL 2-22 
communication with non-PL/I programs 
ending processing 2-22 
interrupting processing 2-22 
PL/I statement CALL 2-22 


S 
S picture character 12-25 
SAMEKEY built-in function 15-21 
scalar 9-4 
assignment 13-1 
data item 5-1 
expression 9-1 
reference 9-1 
value 9-4 
variable 5-1 
scalar data mapping 5-10, 5-11 
scale 12-10 
attributes 
default 12-10 
FIXED 12-10 
FLOAT 12-10 
coded arithmetic data 12-10 
scale factor, precision attribute 12-11 
scope 
attributes 
defaults 12-40, 12-41 
external 4-16, 7-11, 12-40 
internal 4-16, 7-11, 12-40 
of automatic variable 5-16, 12-41 
of based variable 5-16, 12-41 
of condition handling built-in function 
values 10-4 


scope (continued ) 
of contextual declaration 4-13 
of established action 10-4 
of explicit declaration 4-13 
of external procedure name 12-41 
of file constant 12-7 
of internal procedure name 12-41 
of names 3-11 
of open files 7-11 
of static variable 5-16, 12-41 
of values of condition handling built-in 
functions 10-4 
scoping of open files 7-11 
security 6-3 
file authority 6-3 
file ownership 6-3 
SELECT statement 13-18 
select-groups 13-18 
semicolon (;) 4-5 
SEQL attribute 
See SEQUENTIAL attribute 
SEQUENTIAL and DIRECT attributes 11-9, 
11-10, 12-7 
default 11-10 
SEQUENTIAL attribute 11-9, 12-7 
direct access 11-10 
sequential access 11-10 
SET option 11-12, 11-19—11-20 
use with BUFSIZE option of the ENVIRON- 
MENT attribute 7-6 
SEU 
See source entry utility 
sign and currency characters 12-24, 12-25 
- picture character 12-24 
drifting string 
and insertion characters 12-25 
zero suppression 12-25 
S picture character 12-24 
+ picture character 12-24 
$ picture character 12-24 
SIGN built-in function 15-21 
SIGNAL statement 10-4 
conditions in 10-1 
example 10-5 
simple do-group 13-6 
simple statements 4-2, 4-2 
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simple string constant 12-43 
SIN built-in function 15-22 
SIND built-in function 15-22 
SINH built-in function 15-22 
SKIP format item 11-39, 11-40 
skip lines on source program listing 
See “SKIP statement 
SKIP option 11-26 
skip to new page 11-26 
slash (/) B-14 
source entry utility 2-1 
entering source programs 2-1 
PL/I syntax checker 2-2 
source program 
description 2-1 
entering SQL statements 2-5 
PL/I syntax checker 2-2 
using SEU 2-2 
spacing format item 11-40 
special characters B-14 
spooling 6-2 
input 6-2 
output 6-2 
SQL statements in a PL/I program 2-5 
SQRT built-in function 15-22 
statement label 
See label prefix 
statements 4-1, 11-10, 14-7 
ALLOCATE — 5-22 
assignment 4-2, 13-1 
BEGIN 4-11 
CALL 14-7 
CLOSE 11-8 
compound 4-1], 13-13 
IF 13-13 
data transmission 11-2 
DECLARE 7-1, 12-1 
definition 4-1 
DELETE 11-16 
DO 13-5 
elements of 4-2 
END 13-10 
FREE 5-23 
GET 11-24 
GO TO 13-11 
IF 13-13 
input and output 11-1 
ITERATE 13-14 
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statements (continued) 
labels 4-1 
LEAVE 13-15 
nesting 13-14 
null 4-2, 13-17 
ON 10-2 
OPEN 11-4 
OTHERWISE = 13-18 
PROCEDURE 14-2 
PUT 11-25 
READ 11-11 
RETURN 14-4 
REWRITE 11-15 
SELECT 13-18 
SIGNAL 10-4 
simple 4-2 
STOP 13-20 
syntax of 4-1 
types of 4-1 
WHEN 13-18 
WRITE 11-14 
%INCLUDE 2-16 
%PAGE 2-18 
%SKIP 2-19 
static 5-16 
storage 
allocation 5-16 
initialization 5-17 
variables 
STATIC attribute 5-16 
static characters 12-24 
static storage and attribute 5-16, 5-17 
STG (STORAGE) built-in function 15-22 
storage 5-15, 5-16, 5-24 
allocation 
dynamic 5-16 
for automatic variables 5-18 
for based variables 5-19 
for static variables 5-16 
static 5-16 
class 
automatic 5-16 
based 5-16 
default 5-16, 12-41 
static 5-16 
control 
automatic storage 5-18 
based storage 5-19 
built-in functions 15-4 


storage (continued ) 
control (continued) 
static storage 5-16 
requirements 
binary fixed-point value 12-13 
character value 12-18 
decimal floating-point value 12-13 
label value 12-32 
STORAGE built-in function (abbr: STG) 15-22 
storage condition D-5, D-13 
STREAM attribute 11-3, 12-7 
stream data transmission 11-1, 11-3, 11-22—11-44 
apostrophes, treatment of 11-29 
blanks 
insertion of 11-30 
treatment of 11-29 
opening stream files 7-12 
PRINT attnbute 12-8 
program example 8-56 
statements 11-23 
GET 11-23, 11-24 
PUT 11-23, 11-25 
SYSIN file 11-44 
SYSPRINT file 7-12, 11-44 
truncation 11-30 
stream files 7-12 
opening 7-12 
program example 8-56 
use of 8-55 
string 
data assignment 5-25 
string data 
padding 5-25 
truncation 5-25 
string handling built-in functions 15-2 
BIT 15-8 
CHARACTER 15-8 
COPY 15-8 
INDEX 15-12 
LENGTH § 15-12 
SUBSTR = 15-23 
TRANSLATE | 15-24 
UNSPEC 15-25 
VERIFY 15-26 
string length 
calculation 5-29 
for automatic variables 5-19 


string operator 4-4 
string variable length 12-16 
stringsize condition D-5, D-13 
structure 
arrays of 5-5 
assignment 13-1 
component, immediate 5-3 
declaration 5-4, 12-39 
field 5-3 
level number 5-4, 12-39 
logical level 5-3 
major 5-3 
mapping 5-12, 5-15 
combining two units 5-13 
example 5-13—5-15 
maximum level number in DECLARE state- 
ment 5-5, 12-39 
minor 5-3 
parameter descriptor 12-33 
qualification 5-5 
reference 9-1 
variable 5-1 
structure level 
logical 5-4 
number 5-4 
structures 5-3, 5-5 
subfiles of display files 6-9 
example 8-29 
subroutine call 14-7 
subroutines 14-2 
arguments 14-1 
calling 14-1 
data processed 14-1 
parameters 14-1 
return from 14-1 
RETURN statement in 14-4 
subroutines and functions 14-1, 15-5 
subscript list 9-1 
subscripted qualified reference 5-6 
subscripts 5-2, 5-3 
SUBSTR built-in function 15-23 
SUBSTR pseudovariable 15-23 
syntax checker, PL/I 2-2 
syntax diagrams 
how to read vi 
SYSIN file 11-44 
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using messages 3-] J 


using, displaying, and printing messages 3-1 


SYSPRINT file 7-12, 11-44 
SYSTEM option in ON statement 10-3 
system override of member definition for a file 6-2 


system override of PL/I file declarations 6-2 
system-dependent features of PL/I 7-1, 7-20 


T 
TAN built-in function 15-24 
TAND built-in function 15-24 
TANH built-in function 15-24 
target 5-29, 5-31, 5-33 
data attributes 5-27 
length calculation 5-29 
precision calculation 5-29 
target variable 13-1 
test libraries 3-3 
THEN unit 13-13 
TIME built-in function 15-24 
TO option 13-7 
traces 3-7 
example 3-7 
TRANSLATE built-in function 15-24 
TRANSMIT condition D-5, D-13—D-14 
raised by READ 8-64 
raised by READ, WRITE or REWRITE on 
locked record 6-8 


U 
UNDEFINEDFILE condition D-5, D-14—D-16 
raised by COMMITTABLE option 7-7 
raised by level checking 6-12 
raised by OPEN 7-12 
raised by unsuccessful OPEN or CLOSE 7-11 
UNDEFINEDFILE 8-59 
unspecifiable conditions 10-2 
conversion 10-2, D-2 
fixedoverflow 10-2, D-3, D-10 
overflow 10-2, D-4, D-12 
record 10-2, D-4, D-13 
storage D-5, D-13 
stringsize 10-2, D-5, D-13 
underflow 10-2, D-6, D-16 
zerodivide 10-2, D-6, D-16 
UNTIL option 13-6 
UPDATE attribute 11-10, 11-23, 12-7 
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V 
V picture character 12-22 
variables 5-1, 12-38 
automatic 5-18 
based 5-19 
binary fixed-point 12-12 
binary floating-point 12-14 
decimal fixed-point 12-12 
decimal floating-point 12-13 
entry 12-32 
label 12-31 
pointer 12-30 
scalar 5-1 
static 5-16 


W 
WHEN statement 13-18 
WHILE option 13-6 


Y 
— arithmetic operator 9-5, 4-4 
— > (pointer) 4-5 


Z 


Z picture character 12-23 


Numerics 
9 picture character 12-22 


Special Characters 

. (period) 4-5 

. insertion character 12-23 

< comparison operator 9-10, 4-4 
< = comparison operator 9-10, 4-4 
+ arithmetic operator 9-5, 4-4 

+ picture character 12-25 

| bit operator 9-9 

|| concatenation operator 9-14 

|| string operator 4-4 

& bit operator 4-4 

$ currency symbol B-14 


$ picture character 12-24, 12-25 
# arithmetic operator 9-5, 4-4 
* in parameter descriptor list 12-34 
* picture character 12-23 
*PROCESS directive 2-16 
## arithmetic operator 9-5, 4-4 
#/(end comment) 4-5 
— bit operator 4-4 
/ arithmetic operator 9-5, 4-4 
/ insertion character 12-23 
/+ (begin comment) 4-5 
, imsertion character 12-23 
, (comma) 4-5 
%INCLUDE directive 2-16, 2-18 

program examples 8-79 

using for external file descriptions 8-73—8-82 
%PAGE statement 2-18 
%PROCESS directive 2-16, 2-18 
%SKIP statement 2-19, 2-22 
> comparison operator 9-10, 4-4 
> = comparison operator 9-10, 4-4 
: (colon) 4-5 
# number sign B-14 
@ commercial “at” sign B-14 
= assignment symbol 4-5 
= comparison operator 9-10, 4-4 
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